run {cargo}

Run Cargo

Description

This function runs Cargo (Rust's package manager) with the ... arguments passed as command line arguments.

Usage

run(
  ...,
  minimum_version = ".",
  search_methods = c("cache", "convention", "path"),
  leave_no_trace = FALSE,
  environment_variables = list(),
  rustflags = NULL,
  verbose = TRUE,
  run_twice = FALSE,
  stdout = "",
  stderr = ""
)

Arguments

...

Character vector of command line arguments passed to the cargo command.

minimum_version

A character string representing the minimum version of Rust that is needed. Or a path to the root of a package (i.e., the directory containing the DESCRIPTION file), in which case the value is found from the field: SystemRequirements: Cargo (>= XXXX). For the search_methods being "cache", the shell command rustup is used to upgrade the Cargo installation if needed.

search_methods

A character vector potentially containing values "path", "convention", and "cache". This indicates the methods to use (and their order) when searching for a suitable Cargo installation. "path" indicates to try to use base::Sys.which(). "convention" indicates to try to use the directories .cargo in the user's home directory. "cache" indicates to try to use the directory from the cargo package's own installation as given by the tools::R_user_dir('cargo', 'cache').

leave_no_trace

If TRUE, the CARGO_HOME environment variable is set to a temporary directory that is subsequently deleted.

environment_variables

A named character vector providing environment variables which should be temporarily set while running Cargo. Note that the CARGO_HOME and RUSTUP_HOME environment variables are automatically set when using the "cache" search method. Also, the CARGO_HOME environment variable is also set when leave_no_trace == TRUE.

rustflags

A character vector from which the CARGO_ENCODED_RUSTFLAGS environment variables is constructed and then temporarily set. Or, if NULL, this environment variable is left unchanged.

verbose

If TRUE, details of the search for Cargo are shown. If FALSE, no details are shown. If it is a connection, then details are shown and also written to the connection.

run_twice

Should the cargo command be run twice? The environment variable R_CARGO_RUN_COUNTER is set to either 1 or 2 during each run.

stdout

See argument of the same name in base::system2().

stderr

See argument of the same name in base::system2().

Value

The same value and behavior as the base::system2() function, except a non-zero exit code will be given in Cargo is not found.

Examples

if (run("--version") != 0) {
  message("Cargo is not installed. Please run cargo::install() in an interactive session.")
}