# Struct cargo_util::ProcessBuilder

source ·

    pub struct ProcessBuilder {
        program: OsString,
        args: Vec<OsString>,
        env: BTreeMap<String, Option<OsString>>,
        cwd: Option<OsString>,
        wrappers: Vec<OsString>,
        jobserver: Option<Client>,
        display_env_vars: bool,
        retry_with_argfile: bool,
        stdin: Option<Vec<u8>>,
    }

Expand description

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

## Fields§

§`program: OsString`

The program to execute.

§`args: Vec<OsString>`

A list of arguments to pass to the program.

§`env: BTreeMap<String, Option<OsString>>`

Any environment variables that should be set for the program.

§`cwd: Option<OsString>`

The directory to run the program from.

§`wrappers: Vec<OsString>`

A list of wrappers that wrap the original program when calling `ProcessBuilder::wrapped`. The last one is the outermost one.

§`jobserver: Option<Client>`

The `make` jobserver. See the jobserver crate for more information.

§`display_env_vars: bool`

`true` to include environment variable in display.

§`retry_with_argfile: bool`

`true` to retry with an argfile if hitting “command line too big” error. See `ProcessBuilder::retry_with_argfile` for more information.

§`stdin: Option<Vec<u8>>`

Data to write to stdin.

## 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) -> impl Iterator<Item = &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 retry_with_argfile(&mut self, enabled: bool) -> &mut Self

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

source

#### pub fn stdin<T: Into<Vec<u8>>>(&mut self, stdin: T) -> &mut Self

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

source

#### fn should_retry_with_argfile(&self, err: &Error) -> bool

source

#### pub fn status(&self) -> Result<ExitStatus>

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

source

#### fn _status(&self) -> Result<ExitStatus>

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 output(&self) -> Result<Output>

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

source

#### fn _output(&self) -> Result<Output>

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

#### fn build_command_with_argfile(&self) -> Result<(Command, NamedTempFile)>

Builds the command with an `@<path>` argfile that contains all the arguments. This is primarily served for rustc/rustdoc command family.

source

#### fn build_command_without_args(&self) -> Command

Builds a command from `ProcessBuilder` for everything but not `args`.

source

#### pub fn build_command(&self) -> Command

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.

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

## Trait Implementations§

source§

### impl Clone for ProcessBuilder

source§

#### fn clone(&self) -> ProcessBuilder

Returns a copy of the value. Read more
1.0.0 · source§

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
source§

### impl Debug for ProcessBuilder

source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
source§

### impl Display for ProcessBuilder

source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

## Auto Trait Implementations§

§

### impl RefUnwindSafe for ProcessBuilder

§

### impl Send for ProcessBuilder

§

### impl Sync for ProcessBuilder

§

### impl Unpin for ProcessBuilder

§

### impl UnwindSafe for ProcessBuilder

## Blanket Implementations§

source§

### impl<T> Any for Twhere T: 'static + ?Sized,

source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
source§

### impl<T> Borrow<T> for Twhere T: ?Sized,

source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

### impl<T> From<T> for T

source§

#### fn from(t: T) -> T

Returns the argument unchanged.

source§

### impl<T, U> Into<U> for Twhere U: From<T>,

source§

#### fn into(self) -> U

Calls `U::from(self)`.

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

source§

### impl<T> Same<T> for T

§

#### type Output = T

Should always be `Self`
source§

### impl<T> ToOwned for Twhere T: Clone,

§

#### type Owned = T

The resulting type after obtaining ownership.
source§

#### fn to_owned(&self) -> T

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

#### fn clone_into(&self, target: &mut T)

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

### impl<T> ToString for Twhere T: Display + ?Sized,

source§

#### default fn to_string(&self) -> String

Converts the given value to a `String`. Read more
source§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.

## Layout§

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain `repr(...)` attributes. Please see the Rust Reference’s “Type Layout” chapter for details on type layout guarantees.

Size:160 bytes