Struct rustwide::cmd::Command

pub struct Command<'w, 'pl> { /* fields omitted */ }

The Command is a builder to execute system commands and interact with them.

It's a more advanced version of std::process::Command, featuring timeouts, realtime output processing, output logging and sandboxing.

Implementations

impl<'w, 'pl> Command<'w, 'pl>

pub fn new<R: Runnable>(workspace: &'w Workspace, binary: R) -> Self

Create a new, unsandboxed command.

pub fn new_sandboxed<R: Runnable>(
    workspace: &'w Workspace,
    sandbox: SandboxBuilder,
    binary: R
) -> Self

Create a new, sandboxed command.

pub fn args<S: AsRef<OsStr>>(self, args: &[S]) -> Self

Add command-line arguments to the command. This method can be called multiple times to add additional args.

pub fn env<S1: AsRef<OsStr>, S2: AsRef<OsStr>>(self, key: S1, value: S2) -> Self

Add an environment variable to the command.

pub fn cd<P: AsRef<Path>>(self, path: P) -> Self

Change the directory where the command will be executed in.

pub fn timeout(self, timeout: Option<Duration>) -> Self

Set the timeout of this command. If it runs for more time the process will be killed.

Its default value is configured through WorkspaceBuilder::command_timeout.

pub fn no_output_timeout(self, timeout: Option<Duration>) -> Self

Set the no output timeout of this command. If it doesn't output anything for more time the process will be killed.

Its default value is configured through WorkspaceBuilder::command_no_output_timeout.

pub fn process_lines(
    self,
    f: &'pl mut dyn FnMut(&str, &mut ProcessLinesActions)
) -> Self

Set the function that will be called each time a line is outputted to either the standard output or the standard error. Only one function can be set at any time for a command.

The method is useful to analyze the command's output without storing all of it in memory. This example builds a crate and detects compiler errors (ICEs):

let mut ice = false;
Command::new(&workspace, "cargo")
    .args(&["build", "--all"])
    .process_lines(&mut |line, _| {
        if line.contains("internal compiler error") {
            ice = true;
        }
    })
    .run()?;

pub fn log_output(self, log_output: bool) -> Self

Enable or disable logging all the output lines to the log crate. By default logging is enabled.

pub fn log_command(self, log_command: bool) -> Self

Enable or disable logging the command name and args to the log crate before the exectuion. By default logging is enabled.

pub fn run(self) -> Result<(), Error>

Run the prepared command and return an error if it fails (for example with a non-zero exit code or a timeout).

pub fn run_capture(self) -> Result<ProcessOutput, Error>

Run the prepared command and return its output if it succeedes. If it fails (for example with a non-zero exit code or a timeout) an error will be returned instead.

Even though the output will be captured and returned, if output logging is enabled (as it is by default) the output will be also logged. You can disable this behavior by calling the log_output method.