nixos/manual: Refine doc for execute
et al
- Clarify that shellopts are set in every `execute` call (rather than only `succeed`). - Add documentation for the `timeout` parameter and its default values.
This commit is contained in:
parent
4c344da29a
commit
7586158ac9
|
@ -159,23 +159,8 @@ The following methods are available on machine objects:
|
||||||
`execute`
|
`execute`
|
||||||
|
|
||||||
: Execute a shell command, returning a list `(status, stdout)`.
|
: Execute a shell command, returning a list `(status, stdout)`.
|
||||||
If the command detaches, it must close stdout, as `execute` will wait
|
|
||||||
for this to consume all output reliably. This can be achieved by
|
|
||||||
redirecting stdout to stderr `>&2`, to `/dev/console`, `/dev/null` or
|
|
||||||
a file. Examples of detaching commands are `sleep 365d &`, where the
|
|
||||||
shell forks a new process that can write to stdout and `xclip -i`, where
|
|
||||||
the `xclip` command itself forks without closing stdout.
|
|
||||||
Takes an optional parameter `check_return` that defaults to `True`.
|
|
||||||
Setting this parameter to `False` will not check for the return code
|
|
||||||
and return -1 instead. This can be used for commands that shut down
|
|
||||||
the VM and would therefore break the pipe that would be used for
|
|
||||||
retrieving the return code.
|
|
||||||
|
|
||||||
`succeed`
|
Commands are run with `set -euo pipefail` set:
|
||||||
|
|
||||||
: Execute a shell command, raising an exception if the exit status is
|
|
||||||
not zero, otherwise returning the standard output. Commands are run
|
|
||||||
with `set -euo pipefail` set:
|
|
||||||
|
|
||||||
- If several commands are separated by `;` and one fails, the
|
- If several commands are separated by `;` and one fails, the
|
||||||
command as a whole will fail.
|
command as a whole will fail.
|
||||||
|
@ -183,10 +168,33 @@ The following methods are available on machine objects:
|
||||||
- For pipelines, the last non-zero exit status will be returned
|
- For pipelines, the last non-zero exit status will be returned
|
||||||
(if there is one, zero will be returned otherwise).
|
(if there is one, zero will be returned otherwise).
|
||||||
|
|
||||||
- Dereferencing unset variables fail the command.
|
- Dereferencing unset variables fails the command.
|
||||||
|
|
||||||
- It will wait for stdout to be closed. See `execute` for the
|
- It will wait for stdout to be closed.
|
||||||
implications.
|
|
||||||
|
If the command detaches, it must close stdout, as `execute` will wait
|
||||||
|
for this to consume all output reliably. This can be achieved by
|
||||||
|
redirecting stdout to stderr `>&2`, to `/dev/console`, `/dev/null` or
|
||||||
|
a file. Examples of detaching commands are `sleep 365d &`, where the
|
||||||
|
shell forks a new process that can write to stdout and `xclip -i`, where
|
||||||
|
the `xclip` command itself forks without closing stdout.
|
||||||
|
|
||||||
|
Takes an optional parameter `check_return` that defaults to `True`.
|
||||||
|
Setting this parameter to `False` will not check for the return code
|
||||||
|
and return -1 instead. This can be used for commands that shut down
|
||||||
|
the VM and would therefore break the pipe that would be used for
|
||||||
|
retrieving the return code.
|
||||||
|
|
||||||
|
A timeout for the command can be specified (in seconds) using the optional
|
||||||
|
`timeout` parameter, e.g., `execute(cmd, timeout=10)` or
|
||||||
|
`execute(cmd, timeout=None)`. The default is 900 seconds.
|
||||||
|
|
||||||
|
`succeed`
|
||||||
|
|
||||||
|
: Execute a shell command, raising an exception if the exit status is
|
||||||
|
not zero, otherwise returning the standard output. Similar to `execute`,
|
||||||
|
except that the timeout is `None` by default. See `execute` for details on
|
||||||
|
command execution.
|
||||||
|
|
||||||
`fail`
|
`fail`
|
||||||
|
|
||||||
|
@ -196,10 +204,13 @@ The following methods are available on machine objects:
|
||||||
`wait_until_succeeds`
|
`wait_until_succeeds`
|
||||||
|
|
||||||
: Repeat a shell command with 1-second intervals until it succeeds.
|
: Repeat a shell command with 1-second intervals until it succeeds.
|
||||||
|
Has a default timeout of 900 seconds which can be modified, e.g.
|
||||||
|
`wait_until_succeeds(cmd, timeout=10)`. See `execute` for details on
|
||||||
|
command execution.
|
||||||
|
|
||||||
`wait_until_fails`
|
`wait_until_fails`
|
||||||
|
|
||||||
: Repeat a shell command with 1-second intervals until it fails.
|
: Like `wait_until_succeeds`, but repeating the command until it fails.
|
||||||
|
|
||||||
`wait_for_unit`
|
`wait_for_unit`
|
||||||
|
|
||||||
|
|
|
@ -274,35 +274,9 @@ start_all()
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Execute a shell command, returning a list
|
Execute a shell command, returning a list
|
||||||
<literal>(status, stdout)</literal>. If the command
|
<literal>(status, stdout)</literal>.
|
||||||
detaches, it must close stdout, as
|
|
||||||
<literal>execute</literal> will wait for this to consume all
|
|
||||||
output reliably. This can be achieved by redirecting stdout
|
|
||||||
to stderr <literal>>&2</literal>, to
|
|
||||||
<literal>/dev/console</literal>,
|
|
||||||
<literal>/dev/null</literal> or a file. Examples of
|
|
||||||
detaching commands are <literal>sleep 365d &</literal>,
|
|
||||||
where the shell forks a new process that can write to stdout
|
|
||||||
and <literal>xclip -i</literal>, where the
|
|
||||||
<literal>xclip</literal> command itself forks without
|
|
||||||
closing stdout. Takes an optional parameter
|
|
||||||
<literal>check_return</literal> that defaults to
|
|
||||||
<literal>True</literal>. Setting this parameter to
|
|
||||||
<literal>False</literal> will not check for the return code
|
|
||||||
and return -1 instead. This can be used for commands that
|
|
||||||
shut down the VM and would therefore break the pipe that
|
|
||||||
would be used for retrieving the return code.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
<varlistentry>
|
|
||||||
<term>
|
|
||||||
<literal>succeed</literal>
|
|
||||||
</term>
|
|
||||||
<listitem>
|
|
||||||
<para>
|
<para>
|
||||||
Execute a shell command, raising an exception if the exit
|
|
||||||
status is not zero, otherwise returning the standard output.
|
|
||||||
Commands are run with <literal>set -euo pipefail</literal>
|
Commands are run with <literal>set -euo pipefail</literal>
|
||||||
set:
|
set:
|
||||||
</para>
|
</para>
|
||||||
|
@ -323,16 +297,57 @@ start_all()
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Dereferencing unset variables fail the command.
|
Dereferencing unset variables fails the command.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
It will wait for stdout to be closed. See
|
It will wait for stdout to be closed.
|
||||||
<literal>execute</literal> for the implications.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
<para>
|
||||||
|
If the command detaches, it must close stdout, as
|
||||||
|
<literal>execute</literal> will wait for this to consume all
|
||||||
|
output reliably. This can be achieved by redirecting stdout
|
||||||
|
to stderr <literal>>&2</literal>, to
|
||||||
|
<literal>/dev/console</literal>,
|
||||||
|
<literal>/dev/null</literal> or a file. Examples of
|
||||||
|
detaching commands are <literal>sleep 365d &</literal>,
|
||||||
|
where the shell forks a new process that can write to stdout
|
||||||
|
and <literal>xclip -i</literal>, where the
|
||||||
|
<literal>xclip</literal> command itself forks without
|
||||||
|
closing stdout.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
Takes an optional parameter <literal>check_return</literal>
|
||||||
|
that defaults to <literal>True</literal>. Setting this
|
||||||
|
parameter to <literal>False</literal> will not check for the
|
||||||
|
return code and return -1 instead. This can be used for
|
||||||
|
commands that shut down the VM and would therefore break the
|
||||||
|
pipe that would be used for retrieving the return code.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
A timeout for the command can be specified (in seconds)
|
||||||
|
using the optional <literal>timeout</literal> parameter,
|
||||||
|
e.g., <literal>execute(cmd, timeout=10)</literal> or
|
||||||
|
<literal>execute(cmd, timeout=None)</literal>. The default
|
||||||
|
is 900 seconds.
|
||||||
|
</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
<varlistentry>
|
||||||
|
<term>
|
||||||
|
<literal>succeed</literal>
|
||||||
|
</term>
|
||||||
|
<listitem>
|
||||||
|
<para>
|
||||||
|
Execute a shell command, raising an exception if the exit
|
||||||
|
status is not zero, otherwise returning the standard output.
|
||||||
|
Similar to <literal>execute</literal>, except that the
|
||||||
|
timeout is <literal>None</literal> by default. See
|
||||||
|
<literal>execute</literal> for details on command execution.
|
||||||
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
|
@ -353,7 +368,10 @@ start_all()
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Repeat a shell command with 1-second intervals until it
|
Repeat a shell command with 1-second intervals until it
|
||||||
succeeds.
|
succeeds. Has a default timeout of 900 seconds which can be
|
||||||
|
modified, e.g.
|
||||||
|
<literal>wait_until_succeeds(cmd, timeout=10)</literal>. See
|
||||||
|
<literal>execute</literal> for details on command execution.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
@ -363,8 +381,8 @@ start_all()
|
||||||
</term>
|
</term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Repeat a shell command with 1-second intervals until it
|
Like <literal>wait_until_succeeds</literal>, but repeating
|
||||||
fails.
|
the command until it fails.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
Loading…
Reference in a new issue