pub struct ProcessBuilder { /* private fields */ }
Expand description

A builder object for an external process, similar to std::process::Command.

Implementations

Creates a new ProcessBuilder with the given executable path.

(chainable) Sets the executable for the process.

(chainable) Adds arg to the args list.

(chainable) Adds multiple args to the args list.

(chainable) Replaces the args list with the given args.

(chainable) Sets the current working directory of the process.

(chainable) Sets an environment variable for the process.

(chainable) Unsets an environment variable for the process.

Gets the executable name.

Gets the program arguments.

Gets the current working directory for the process.

Gets an environment variable as the process will see it (will inherit from environment unless explicitally unset).

Gets all environment variables explicitly set or unset for the process (not inherited vars).

Sets the make jobserver. See the jobserver crate for more information.

Enables environment variable display.

Enables retrying with an argfile if hitting “command line too big” error

This is primarily for the @path arg of rustc and rustdoc, which treat each line as an command-line argument, so LF and CRLF bytes are not valid as an argument for argfile at this moment. For example, RUSTDOCFLAGS="--crate-version foo\nbar" cargo doc is valid when invoking from command-line but not from argfile.

To sum up, the limitations of the argfile are:

  • Must be valid UTF-8 encoded.
  • Must not contain any newlines in each argument.

Ref:

  • https://doc.rust-lang.org/rustdoc/command-line-arguments.html#path-load-command-line-flags-from-a-path
  • https://doc.rust-lang.org/rustc/command-line-arguments.html#path-load-command-line-flags-from-a-path>

Sets a value that will be written to stdin of the process on launch.

Like Command::status but with a better error message.

Runs the process, waiting for completion, and mapping non-success exit codes to an error.

Replaces the current process with the target process.

On Unix, this executes the process using the Unix syscall execvp, which will block this process, and will only return if there is an error.

On Windows this isn’t technically possible. Instead we emulate it to the best of our ability. One aspect we fix here is that we specify a handler for the Ctrl-C handler. In doing so (and by effectively ignoring it) we should emulate proxying Ctrl-C handling to the application at hand, which will either terminate or handle it itself. According to Microsoft’s documentation at https://docs.microsoft.com/en-us/windows/console/ctrl-c-and-ctrl-break-signals. the Ctrl-C signal is sent to all processes attached to a terminal, which should include our child process. If the child terminates then we’ll reap them in Cargo pretty quickly, and if the child handles the signal then we won’t terminate (and we shouldn’t!) until the process itself later exits.

Like Command::output but with a better error message.

Executes the process, returning the stdio output, or an error if non-zero exit status.

Executes a command, passing each line of stdout and stderr to the supplied callbacks, which can mutate the string data.

If any invocations of these function return an error, it will be propagated.

If capture_output is true, then all the output will also be buffered and stored in the returned Output object. If it is false, no caching is done, and the callbacks are solely responsible for handling the output.

Converts ProcessBuilder into a std::process::Command, and handles the jobserver, if present.

Note that this method doesn’t take argfile fallback into account. The caller should handle it by themselves.

Wraps an existing command with the provided wrapper, if it is present and valid.

Examples
use cargo_util::ProcessBuilder;
// Running this would execute `rustc`
let cmd = ProcessBuilder::new("rustc");

// Running this will execute `sccache rustc`
let cmd = cmd.wrapped(Some("sccache"));

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Formats the value using the given formatter. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.