Struct cargo_util::ProcessBuilder

source · [−]

pub struct ProcessBuilder { /* private fields */ }

Expand description

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

Implementations

source

impl ProcessBuilder

source

pub fn new<T: AsRef<OsStr>>(cmd: T) -> ProcessBuilder

Creates a new ProcessBuilder with the given executable path.

source

pub fn program<T: AsRef<OsStr>>(&mut self, program: T) -> &mut ProcessBuilder

(chainable) Sets the executable for the process.

source

pub fn arg<T: AsRef<OsStr>>(&mut self, arg: T) -> &mut ProcessBuilder

(chainable) Adds arg to the args list.

source

pub fn args<T: AsRef<OsStr>>(&mut self, args: &[T]) -> &mut ProcessBuilder

(chainable) Adds multiple args to the args list.

source

pub fn args_replace<T: AsRef<OsStr>>(
&mut self,
args: &[T]
) -> &mut ProcessBuilder

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

source

pub fn cwd<T: AsRef<OsStr>>(&mut self, path: T) -> &mut ProcessBuilder

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

source

pub fn env<T: AsRef<OsStr>>(&mut self, key: &str, val: T) -> &mut ProcessBuilder

(chainable) Sets an environment variable for the process.

source

pub fn env_remove(&mut self, key: &str) -> &mut ProcessBuilder

(chainable) Unsets an environment variable for the process.

source

pub fn get_program(&self) -> &OsString

Gets the executable name.

source

pub fn get_args(&self) -> &[OsString ]

Gets the program arguments.

source

pub fn get_cwd(&self) -> Option<&Path>

Gets the current working directory for the process.

source

pub fn get_env(&self, var: &str) -> Option<OsString>

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

source

pub fn get_envs(&self) -> &BTreeMap<String, Option<OsString>>

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

source

pub fn inherit_jobserver(&mut self, jobserver: &Client) -> &mut Self

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

source

pub fn display_env_vars(&mut self) -> &mut Self

Enables environment variable display.

source

pub fn exec(&self) -> Result<()>

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

source

pub fn exec_replace(&self) -> Result<()>

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.

source

pub fn exec_with_output(&self) -> Result<Output>

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

source

pub fn exec_with_streaming(
 &self,
 on_stdout_line: &mut dyn FnMut(&str) -> Result<()>,
 on_stderr_line: &mut dyn FnMut(&str) -> Result<()>,
 capture_output: bool
) -> Result<Output>

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.

source

pub fn build_command(&self) -> Command

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

source

pub fn wrapped(self, wrapper: Option<impl AsRef<OsStr>>) -> Self

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"));