diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index e8ae3ff8735..e8d5d9854ff 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -363,21 +363,22 @@ Cargo [configuration location](config.md). ```toml [target.x86_64-unknown-linux-gnu.foo] -rustc-link-search = ["/path/to/foo"] rustc-link-lib = ["foo"] -root = "/path/to/foo" -key = "value" +rustc-link-search = ["/path/to/foo"] +rustc-flags = "-L /some/path" +rustc-cfg = ['key="value"'] +rustc-env = {key = "value"} +rustc-cdylib-link-arg = ["…"] +metadata_key1 = "value" +metadata_key2 = "value" ``` -This section states that for the target `x86_64-unknown-linux-gnu` the library -named `foo` has the metadata specified. This metadata is the same as the -metadata generated as if the build script had run, providing a number of -key/value pairs where the `rustc-flags`, `rustc-link-search`, and -`rustc-link-lib` keys are slightly special. - With this configuration, if a package declares that it links to `foo` then the build script will **not** be compiled or run, and the metadata specified will -instead be used. +be used instead. + +The `warning`, `rerun-if-changed`, and `rerun-if-env-changed` keys should not +be used and will be ignored. ### Jobserver diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md index ae6bcd8ac00..054a5b94db9 100644 --- a/src/doc/src/reference/config.md +++ b/src/doc/src/reference/config.md @@ -1,190 +1,174 @@ ## Configuration -This document will explain how Cargo’s configuration system works, as well as +This document explains how Cargo’s configuration system works, as well as available keys or configuration. For configuration of a package through its manifest, see the [manifest format](manifest.md). ### Hierarchical structure Cargo allows local configuration for a particular package as well as global -configuration, like git. Cargo extends this to a hierarchical strategy. -If, for example, Cargo were invoked in `/projects/foo/bar/baz`, then the -following configuration files would be probed for and unified in this order: +configuration. It looks for configuration files in the current directory and +all parent directories. If, for example, Cargo were invoked in +`/projects/foo/bar/baz`, then the following configuration files would be +probed for and unified in this order: * `/projects/foo/bar/baz/.cargo/config` * `/projects/foo/bar/.cargo/config` * `/projects/foo/.cargo/config` * `/projects/.cargo/config` * `/.cargo/config` -* `$CARGO_HOME/config` (`$CARGO_HOME` defaults to `$HOME/.cargo`) +* `$CARGO_HOME/config` which defaults to: + * Windows: `%USERPROFILE%\.cargo\config` + * Unix: `$HOME/.cargo/config` With this structure, you can specify configuration per-package, and even possibly check it into version control. You can also specify personal defaults with a configuration file in your home directory. -### Configuration format - -All configuration is currently in the [TOML format][toml] (like the manifest), -with simple key-value pairs inside of sections (tables) which all get merged -together. - -[toml]: https://github.com/toml-lang/toml +If a key is specified in multiple config files, the values will get merged +together. Numbers, strings, and booleans will use the value in the deeper +config directory taking precedence over ancestor directories, where the +home directory is the lowest priority. Arrays will be joined together. -### Configuration keys - -All of the following keys are optional, and their defaults are listed as their -value unless otherwise noted. +### Configuration format -Key values that specify a tool may be given as an absolute path, a relative path -or as a pathless tool name. Absolute paths and pathless tool names are used as -given. Relative paths are resolved relative to the parent directory of the -`.cargo` directory of the config file that the value resides within. +Configuration files are written in the [TOML format][toml] (like the +manifest), with simple key-value pairs inside of sections (tables). The +following is a quick overview of all settings, with detailed descriptions +found below. ```toml -# An array of paths to local repositories which are to be used as overrides for -# dependencies. For more information see the Specifying Dependencies guide. -paths = ["/path/to/override"] - -[cargo-new] -# This is your name/email to place in the `authors` section of a new Cargo.toml -# that is generated. If not present, then `git` will be probed, and if that is -# not present then `$USER` and `$EMAIL` will be used. -name = "..." -email = "..." - -# By default `cargo new` will initialize a new Git repository. This key can -# be set to change the version control system used. Valid values are `git`, -# `hg` (for Mercurial), `pijul`, `fossil`, or `none` to disable this behavior. -vcs = "none" - -# For the following sections, $triple refers to any valid target triple, not the -# literal string "$triple", and it will apply whenever that target triple is -# being compiled to. 'cfg(...)' refers to the Rust-like `#[cfg]` syntax for -# conditional compilation. -[target.$triple] -# This is the linker which is passed to rustc (via `-C linker=`) when the `$triple` -# is being compiled for. By default this flag is not passed to the compiler. -linker = ".." -# Same but for the library archiver which is passed to rustc via `-C ar=`. -ar = ".." -# If a runner is provided, compiled targets for the `$triple` will be executed -# by invoking the specified runner executable with actual target as first argument. -# This applies to `cargo run`, `cargo test` and `cargo bench` commands. -# By default compiled targets are executed directly. -runner = ".." -# custom flags to pass to all compiler invocations that target $triple -# this value overrides build.rustflags when both are present -rustflags = ["..", ".."] - -# A package with the `links` key can override the build script with a -# table with the name of the `links` library. -[target.$triple.$links] -# Any build script outputs may be included here as separate keys. -rustc-link-search = ["/path/to/foo"] -rustc-link-lib = ["foo"] - -[target.'cfg(...)'] -# Similar for the $triple configuration, but using the `cfg` syntax. -# If several `cfg` and $triple targets are candidates, then the rustflags -# are concatenated. The `cfg` syntax only applies to rustflags, and not to -# linker. -rustflags = ["..", ".."] -# Similar for the $triple configuration, but using the `cfg` syntax. -# If one or more `cfg`s, and a $triple target are candidates, then the $triple -# will be used -# If several `cfg` are candidates, then the build will error -runner = ".." - -# Configuration keys related to the registry -[registry] -index = "..." # URL of the registry index (defaults to the index of crates.io) -default = "..." # Name of the default registry to use (can be overridden with - # --registry) - -# Configuration keys for registries other than crates.io. -# `$name` should be the name of the registry, which will be used for -# dependencies in `Cargo.toml` files and the `--registry` command-line flag. -# Registry names should only contain alphanumeric characters, `-`, or `_`. -[registries.$name] -index = "..." # URL of the registry index +paths = ["/path/to/override"] # path dependency overrides -[http] -proxy = "host:port" # HTTP proxy to use for HTTP requests (defaults to none) - # in libcurl format, e.g., "socks5h://host:port" -timeout = 30 # Timeout for each HTTP request, in seconds -cainfo = "cert.pem" # Path to Certificate Authority (CA) bundle (optional) -check-revoke = true # Indicates whether SSL certs are checked for revocation -ssl-version = "tlsv1.3" # Indicates which SSL version or above to use (options are - # "default", "tlsv1", "tlsv1.0", "tlsv1.1", "tlsv1.2", "tlsv1.3") - # To better control SSL version, we can even use - # `ssl-version.min = "..."` and `ssl-version.max = "..."` - # where "..." is one of the above options. But note these two forms - # ("setting `ssl-version`" and "setting both `min`/`max`) - # can't co-exist. -low-speed-limit = 5 # Lower threshold for bytes/sec (10 = default, 0 = disabled) -multiplexing = true # whether or not to use HTTP/2 multiplexing where possible - -# This setting can be used to help debug what's going on with HTTP requests made -# by Cargo. When set to `true` then Cargo's normal debug logging will be filled -# in with HTTP information, which you can extract with -# `CARGO_LOG=cargo::ops::registry=debug` (and `trace` may print more). -# -# Be wary when posting these logs elsewhere though, it may be the case that a -# header has an authentication token in it you don't want leaked! Be sure to -# briefly review logs before posting them. -debug = false +[alias] # command aliases +b = "build" +c = "check" +t = "test" +r = "run" +rr = "run --release" +space_example = ["run", "--release", "--", "\"command list\""] [build] jobs = 1 # number of parallel jobs, defaults to # of CPUs rustc = "rustc" # the rust compiler tool -rustc-wrapper = ".." # run this wrapper instead of `rustc`; useful to set up a - # build cache tool such as `sccache` +rustc-wrapper = "…" # run this wrapper instead of `rustc` rustdoc = "rustdoc" # the doc generator tool target = "triple" # build for the target triple (ignored by `cargo install`) target-dir = "target" # path of where to place all generated artifacts -rustflags = ["..", ".."] # custom flags to pass to all compiler invocations -rustdocflags = ["..", ".."] # custom flags to pass to rustdoc +rustflags = ["…", "…"] # custom flags to pass to all compiler invocations +rustdocflags = ["…", "…"] # custom flags to pass to rustdoc incremental = true # whether or not to enable incremental compilation - # If `incremental` is not set, then the value from - # the profile is used. -dep-info-basedir = ".." # full path for the base directory for targets in depfiles +dep-info-basedir = "…" # path for the base directory for targets in depfiles +pipelining = true # rustc pipelining -[term] -verbose = false # whether cargo provides verbose output -color = 'auto' # whether cargo colorizes output +[cargo-new] +name = "Your Name" # name to use in `authors` field +email = "you@example.com" # email address to use in `authors` field +vcs = "none" # VCS to use ('git', 'hg', 'pijul', 'fossil', 'none') + +[http] +debug = false # HTTP debugging +proxy = "host:port" # HTTP proxy in libcurl format +ssl-version = "tlsv1.3" # TLS version to use +ssl-version.max = "tlsv1.3" # maximum TLS version +ssl-version.min = "tlsv1.1" # minimum TLS version +timeout = 30 # timeout for each HTTP request, in seconds +low-speed-limit = 10 # network timeout threshold (bytes/sec) +cainfo = "cert.pem" # path to Certificate Authority (CA) bundle +check-revoke = true # check for SSL certificate revocation +multiplexing = true # HTTP/2 multiplexing +user-agent = "…" # the user-agent header + +[install] +root = "/some/path" # `cargo install` destination directory -# Network configuration [net] -retry = 2 # number of times a network call will automatically retried -git-fetch-with-cli = false # if `true` we'll use `git`-the-CLI to fetch git repos -offline = false # do not access the network, but otherwise try to proceed if possible +retry = 2 # network retries +git-fetch-with-cli = true # use the `git` executable for git operations +offline = false # do not access the network -# Alias cargo commands. The first 4 aliases are built in. If your -# command requires grouped whitespace use the list format. -[alias] -b = "build" -c = "check" -t = "test" -r = "run" -rr = "run --release" -space_example = ["run", "--release", "--", "\"command list\""] +[registries.] # registries other than crates.io +index = "…" # URL of the registry index +token = "…" # authentication token for the registry + +[registry] +default = "…" # name of the default registry +token = "…" # authentication token for crates.io + +[source.] # source definition and replacement +replace-with = "…" # replace this source with the given named source +directory = "…" # path to a directory source +registry = "…" # URL to a registry source +local-registry = "…" # path to a local registry source +git = "…" # URL of a git repository source +branch = "…" # branch name for the git repository +tag = "…" # tag name for the git repository +rev = "…" # revision for the git repository + +[target.] +linker = "…" # linker to use +runner = "…" # wrapper to run executables +rustflags = ["…", "…"] # custom flags for `rustc` + +[target.] +runner = "…" # wrapper to run executables +rustflags = ["…", "…"] # custom flags for `rustc` + +[target..] # `links` build script override +rustc-link-lib = ["foo"] +rustc-link-search = ["/path/to/foo"] +rustc-flags = ["-L", "/some/path"] +rustc-cfg = ['key="value"'] +rustc-env = {key = "value"} +rustc-cdylib-link-arg = ["…"] +metadata_key1 = "value" +metadata_key2 = "value" + +[term] +verbose = false # whether cargo provides verbose output +color = 'auto' # whether cargo colorizes output ``` ### Environment variables Cargo can also be configured through environment variables in addition to the -TOML syntax above. For each configuration key above of the form `foo.bar` the -environment variable `CARGO_FOO_BAR` can also be used to define the value. For -example the `build.jobs` key can also be defined by `CARGO_BUILD_JOBS`. - -Environment variables will take precedent over TOML configuration, and currently -only integer, boolean, and string keys are supported to be defined by -environment variables. This means that [source replacement][source], which is expressed by -tables, cannot be configured through environment variables. +TOML configuration files. For each configuration key of the form `foo.bar` the +environment variable `CARGO_FOO_BAR` can also be used to define the value. +Keys are converted to uppercase, dots and dashes are converted to underscores. +For example the `target.x86_64-unknown-linux-gnu.runner` key can also be +defined by the `CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUNNER` environment +variable. + +Environment variables will take precedence over TOML configuration files. +Currently only integer, boolean, string and some array values are supported to +be defined by environment variables. Descriptions below indicate which keys +support environment variables. In addition to the system above, Cargo recognizes a few other specific [environment variables][env]. +### Config-relative paths + +Paths in config files may be absolute, relative, or a bare name without any +path separators. Paths for executables without a path separator will use the +`PATH` environment variable to search for the executable. Paths for +non-executables will be relative to where the config value is defined. For +config files, that is relative to the parent directory of the `.cargo` +directory where the value was defined. For environment variables it is +relative to the current working directory. + +```toml +# Relative path examples. + +[target.x86_64-unknown-linux-gnu] +runner = "foo" # Searches `PATH` for `foo`. + +[source.vendored-sources] +# Directory is relative to the parent where `.cargo/config` is located. +# For example, `/my/project/.cargo/config` would result in `/my/project/vendor`. +directory = "vendor" +``` + ### Credentials Configuration values with sensitive information are stored in the @@ -193,12 +177,10 @@ by [`cargo login`]. It follows the same format as Cargo config files. ```toml [registry] -token = "..." # Access token for crates.io +token = "…" # Access token for crates.io -# `$name` should be a registry name (see above for more information about -# configuring registries). -[registries.$name] -token = "..." # Access token for the named registry +[registries.] +token = "…" # Access token for the named registry ``` Tokens are used by some Cargo commands such as [`cargo publish`] for @@ -206,13 +188,636 @@ authenticating with remote registries. Care should be taken to protect the tokens and to keep them secret. As with most other config values, tokens may be specified with environment -variables. The token for crates.io may be specified with the +variables. The token for [crates.io] may be specified with the `CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may be specified with environment variables of the form -`CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name of the registry in all -capital letters. +`CARGO_REGISTRIES__TOKEN` where `` is the name of the registry in +all capital letters. + +### Configuration keys + +This section documents all configuration keys. The description for keys with +variable parts are annotated with angled brackets like `target.` where +the `` part can be any target triple like +`target.x86_64-pc-windows-msvc`. + +#### `paths` +* Type: array of strings (paths) +* Default: none +* Environment: not supported + +An array of paths to local packages which are to be used as overrides for +dependencies. For more information see the [Specifying Dependencies +guide](specifying-dependencies.md#overriding-with-local-dependencies). + +#### `[alias]` +* Type: string or array of strings +* Default: see below +* Environment: `CARGO_ALIAS_` + +The `[alias]` table defines CLI command aliases. For example, running `cargo +b` is an alias for running `cargo build`. Each key in the table is the +subcommand, and the value is the actual command to run. The value may be an +array of strings, where the first element is the command and the following are +arguments. It may also be a string, which will be split on spaces into +subcommand and arguments. The following aliases are built-in to Cargo: + +```toml +[alias] +b = "build" +c = "check" +t = "test" +r = "run" +``` + +Aliases are not allowed to redefine existing built-in commands. + +#### `[build]` + +The `[build]` table controls build-time operations and compiler settings. + +##### `build.jobs` +* Type: integer +* Default: number of logical CPUs +* Environment: `CARGO_BUILD_JOBS` + +Sets the maximum number of compiler processes to run in parallel. + +Can be overridden with the `--jobs` CLI option. + +##### `build.rustc` +* Type: string (program path) +* Default: "rustc" +* Environment: `CARGO_BUILD_RUSTC` or `RUSTC` + +Sets the executable to use for `rustc`. + +##### `build.rustc-wrapper` +* Type: string (program path) +* Default: none +* Environment: `CARGO_BUILD_RUSTC_WRAPPER` or `RUSTC_WRAPPER` + +Sets a wrapper to execute instead of `rustc`. The first argument passed to the +wrapper is the path to the actual `rustc`. + +##### `build.rustdoc` +* Type: string (program path) +* Default: "rustdoc" +* Environment: `CARGO_BUILD_RUSTDOC` or `RUSTDOC` + +Sets the executable to use for `rustdoc`. + +##### `build.target` +* Type: string +* Default: host platform +* Environment: `CARGO_BUILD_TARGET` + +The default target platform triple to compile to. + +This may also be a relative path to a `.json` target spec file. + +Can be overridden with the `--target` CLI option. + +##### `build.target-dir` +* Type: string (path) +* Default: "target" +* Environment: `CARGO_BUILD_TARGET_DIR` or `CARGO_TARGET_DIR` + +The path to where all compiler output is placed. The default if not specified +is a directory named `target` located at the root of the workspace. + +Can be overridden with the `--target-dir` CLI option. + +##### `build.rustflags` +* Type: string or array of strings +* Default: none +* Environment: `CARGO_BUILD_RUSTFLAGS` or `RUSTFLAGS` + +Extra command-line flags to pass to `rustc`. The value may be a array of +strings or a space-separated string. + +There are three mutually exclusive sources of extra flags. They are checked in +order, with the first one being used: + +1. `RUSTFLAGS` environment variable. +2. All matching `target..rustflags` and `target..rustflags` + config entries joined together. +3. `build.rustflags` config value. + +Additional flags may also be passed with the [`cargo rustc`] command. + +If the `--target` flag (or [`build.target`](#buildtarget)) is used, then the +flags will only be passed to the compiler for the target. Things being built +for the host, such as build scripts or proc macros, will not receive the args. +Without `--target`, the flags will be passed to all compiler invocations +(including build scripts and proc macros) because dependencies are shared. If +you have args that you do not want to pass to build scripts or proc macros and +are building for the host, pass `--target` with the host triple. + +##### `build.rustdocflags` +* Type: string or array of strings +* Default: none +* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `RUSTDOCFLAGS` + +Extra command-line flags to pass to `rustdoc`. The value may be a array of +strings or a space-separated string. + +There are two mutually exclusive sources of extra flags. They are checked in +order, with the first one being used: + +1. `RUSTDOCFLAGS` environment variable. +2. `build.rustdocflags` config value. + +Additional flags may also be passed with the [`cargo rustdoc`] command. + +##### `build.incremental` +* Type: bool +* Default: from profile +* Environment: `CARGO_BUILD_INCREMENTAL` or `CARGO_INCREMENTAL` + +Whether or not to perform [incremental compilation]. The default if not set is +to use the value from the [profile]. Otherwise this overrides the setting of +all profiles. + +The `CARGO_INCREMENTAL` environment variable can be set to `1` to force enable +incremental compilation for all profiles, or `0` to disable it. This env var +overrides the config setting. + +##### `build.dep-info-basedir` +* Type: string (path) +* Default: none +* Environment: `CARGO_BUILD_DEP_INFO_BASEDIR` + +Strips the given path prefix from dep info file paths. + +Cargo saves a "dep info" file with a `.d` suffix which is a Makefile-like +syntax that indicates all of the file dependencies required to rebuild the +artifact. These are intended to be used with external build systems so that +they can detect if Cargo needs to be re-executed. The paths in the file are +absolute by default. This config setting can be set to strip the given prefix +from all of the paths for tools that require relative paths. + +The setting itself is a config-relative path. So, for example, a value of +`"."` would strip all paths starting with the parent directory of the `.cargo` +directory. + +##### `build.pipelining` +* Type: boolean +* Default: true +* Environment: `CARGO_BUILD_PIPELINING` + +Controls whether or not build pipelining is used. This allows Cargo to +schedule overlapping invocations of `rustc` in parallel when possible. + +#### `[cargo-new]` + +The `[cargo-new]` table defines defaults for the [`cargo new`] command. + +##### `cargo-new.name` +* Type: string +* Default: from environment +* Environment: `CARGO_NAME` or `CARGO_CARGO_NEW_NAME` + +Defines the name to use in the `authors` field when creating a new +`Cargo.toml` file. If not specified in the config, Cargo searches the +environment or your `git` configuration as described in the [`cargo new`] +documentation. + +##### `cargo-new.email` +* Type: string +* Default: from environment +* Environment: `CARGO_EMAIL` or `CARGO_CARGO_NEW_EMAIL` + +Defines the email address used in the `authors` field when creating a new +`Cargo.toml` file. If not specified in the config, Cargo searches the +environment or your `git` configuration as described in the [`cargo new`] +documentation. The `email` value may be set to an empty string to prevent +Cargo from placing an address in the authors field. + +##### `cargo-new.vcs` +* Type: string +* Default: "git" or "none" +* Environment: `CARGO_CARGO_NEW_VCS` + +Specifies the source control system to use for initializing a new repository. +Valid values are `git`, `hg` (for Mercurial), `pijul`, `fossil` or `none` to +disable this behavior. Defaults to `git`, or `none` if already inside a VCS +repository. Can be overridden with the `--vcs` CLI option. + +#### `[http]` + +The `[http]` table defines settings for HTTP behavior. This includes fetching +crate dependencies and accessing remote git repositories. + +##### `http.debug` +* Type: boolean +* Default: false +* Environment: `CARGO_HTTP_DEBUG` + +If `true`, enables debugging of HTTP requests. The debug information can be +seen by setting the `CARGO_LOG=cargo::ops::registry=debug` environment +variable (or use `trace` for even more information). + +Be wary when posting logs from this output in a public location. The output +may include headers with authentication tokens which you don't want to leak! +Be sure to review logs before posting them. +##### `http.proxy` +* Type: string +* Default: none +* Environment: `CARGO_HTTP_PROXY` or `HTTPS_PROXY` or `https_proxy` or `http_proxy` + +Sets an HTTP and HTTPS proxy to use. The format is in [libcurl format] as in +`[protocol://]host[:port]`. If not set, Cargo will also check the `http.proxy` +setting in your global git configuration. If none of those are set, the +`HTTPS_PROXY` or `https_proxy` environment variables set the proxy for HTTPS +requests, and `http_proxy` sets it for HTTP requests. + +##### `http.timeout` +* Type: integer +* Default: 30 +* Environment: `CARGO_HTTP_TIMEOUT` or `HTTP_TIMEOUT` + +Sets the timeout for each HTTP request, in seconds. + +##### `http.cainfo` +* Type: string (path) +* Default: none +* Environment: `CARGO_HTTP_CAINFO` + +Path to a Certificate Authority (CA) bundle file, used to verify TLS +certificates. If not specified, Cargo attempts to use the system certificates. + +##### `http.check-revoke` +* Type: boolean +* Default: true (Windows) false (all others) +* Environment: `CARGO_HTTP_CHECK_REVOKE` + +This determines whether or not TLS certificate revocation checks should be +performed. This only works on Windows. + +##### `http.ssl-version` +* Type: string or min/max table +* Default: none +* Environment: `CARGO_HTTP_SSL_VERSION` + +This sets the minimum TLS version to use. It takes a string, with one of the +possible values of "default", "tlsv1", "tlsv1.0", "tlsv1.1", "tlsv1.2", or +"tlsv1.3". + +This may alternatively take a table with two keys, `min` and `max`, which each +take a string value of the same kind that specifies the minimum and maximum +range of TLS versions to use. + +The default is a minimum version of "tlsv1.0" and a max of the newest version +supported on your platform, typically "tlsv1.3". + +##### `http.low-speed-limit` +* Type: integer +* Default: 10 +* Environment: `CARGO_HTTP_LOW_SPEED_LIMIT` + +This setting controls timeout behavior for slow connections. If the average +transfer speed in bytes per second is below the given value for +[`http.timeout`](#httptimeout) seconds (default 30 seconds), then the +connection is considered too slow and Cargo will abort and retry. + +##### `http.multiplexing` +* Type: boolean +* Default: true +* Environment: `CARGO_HTTP_MULTIPLEXING` + +When `true`, Cargo will attempt to use the HTTP2 protocol with multiplexing. +This allows multiple requests to use the same connection, usually improving +performance when fetching multiple files. If `false`, Cargo will use HTTP 1.1 +without pipelining. + +##### `http.user-agent` +* Type: string +* Default: Cargo's version +* Environment: `CARGO_HTTP_USER_AGENT` + +Specifies a custom user-agent header to use. The default if not specified is a +string that includes Cargo's version. + +#### `[install]` + +The `[install]` table defines defaults for the [`cargo install`] command. + +##### `install.root` +* Type: string (path) +* Default: Cargo's home directory +* Environment: `CARGO_INSTALL_ROOT` + +Sets the path to the root directory for installing executables for [`cargo +install`]. Executables go into a `bin` directory underneath the root. + +The default if not specified is Cargo's home directory (default `.cargo` in +your home directory). + +Can be overridden with the `--root` command-line option. + +#### `[net]` + +The `[net]` table controls networking configuration. + +##### `net.retry` +* Type: integer +* Default: 2 +* Environment: `CARGO_NET_RETRY` + +Number of times to retry possibly spurious network errors. + +##### `net.git-fetch-with-cli` +* Type: boolean +* Default: false +* Environment: `CARGO_NET_GIT_FETCH_WITH_CLI` + +If this is `true`, then Cargo will use the `git` executable to fetch registry +indexes and git dependencies. If `false`, then it uses a built-in `git` +library. + +Setting this to `true` can be helpful if you have special authentication +requirements that Cargo does not support. + +##### `net.offline` +* Type: boolean +* Default: false +* Environment: `CARGO_NET_OFFLINE` + +If this is `true`, then Cargo will avoid accessing the network, and attempt to +proceed with locally cached data. If `false`, Cargo will access the network as +needed, and generate an error if it encounters a network error. + +Can be overridden with the `--offline` command-line option. + +#### `[registries]` + +The `[registries]` table is used for specifying additional [registries]. It +consists of a sub-table for each named registry. + +##### `registries..index` +* Type: string (url) +* Default: none +* Environment: `CARGO_REGISTRIES__INDEX` + +Specifies the URL of the git index for the registry. + +##### `registries..token` +* Type: string +* Default: none +* Environment: `CARGO_REGISTRIES__TOKEN` + +Specifies the authentication token for the given registry. This value should +only appear in the [credentials](#credentials) file. This is used for registry +commands like [`cargo publish`] that require authentication. + +Can be overridden with the `--token` command-line option. + +#### `[registry]` + +The `[registry]` table controls the default registry used when one is not +specified. + +##### `registry.index` + +This value is deprecated and should not be used. + +##### `registry.default` +* Type: string +* Default: `"crates-io"` +* Environment: `CARGO_REGISTRY_DEFAULT` + +The name of the registry (from the [`registries` table](#registries)) to use +by default for registry commands like [`cargo publish`]. + +Can be overridden with the `--registry` command-line option. + +##### `registry.token` +* Type: string +* Default: none +* Environment: `CARGO_REGISTRY_TOKEN` + +Specifies the authentication token for [crates.io]. This value should only +appear in the [credentials](#credentials) file. This is used for registry +commands like [`cargo publish`] that require authentication. + +Can be overridden with the `--token` command-line option. + +#### `[source]` + +The `[source]` table defines the registry sources available. See [Source +Replacement] for more information. It consists of a sub-table for each named +source. A source should only define one kind (directory, registry, +local-registry, or git). + +##### `source..replace-with` +* Type: string +* Default: none +* Environment: not supported + +If set, replace this source with the given named source. + +##### `source..directory` +* Type: string (path) +* Default: none +* Environment: not supported + +Sets the path to a directory to use as a directory source. + +##### `source..registry` +* Type: string (url) +* Default: none +* Environment: not supported + +Sets the URL to use for a registry source. + +##### `source..local-registry` +* Type: string (path) +* Default: none +* Environment: not supported + +Sets the path to a directory to use as a local registry source. + +##### `source..git` +* Type: string (url) +* Default: none +* Environment: not supported + +Sets the URL to use for a git repository source. + +##### `source..branch` +* Type: string +* Default: none +* Environment: not supported + +Sets the branch name to use for a git repository. + +If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. + +##### `source..tag` +* Type: string +* Default: none +* Environment: not supported + +Sets the tag name to use for a git repository. + +If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. + +##### `source..rev` +* Type: string +* Default: none +* Environment: not supported + +Sets the [revision] to use for a git repository. + +If none of `branch`, `tag`, or `rev` is set, defaults to the `master` branch. + + +#### `[target]` + +The `[target]` table is used for specifying settings for specific platform +targets. It consists of a sub-table which is either a platform triple or a +[`cfg()` expression]. The given values will be used if the target platform +matches either the `` value or the `` expression. + +```toml +[target.thumbv7m-none-eabi] +linker = "arm-none-eabi-gcc" +runner = "my-emulator" +rustflags = ["…", "…"] + +[target.'cfg(all(target_arch = "arm", target_os = "none"))'] +runner = "my-arm-wrapper" +rustflags = ["…", "…"] +``` + +`cfg` values come from those built-in to the compiler (run `rustc --print=cfg` +to view), values set by [build scripts], and extra `--cfg` flags passed to +`rustc` (such as those defined in `RUSTFLAGS`). Do not try to match on +`debug_assertions` or Cargo features like `feature="foo"`. + +If using a target spec JSON file, the `` value is the filename stem. +For example `--target foo/bar.json` would match `[target.bar]`. + +##### `target..ar` + +This option is deprecated and unused. + +##### `target..linker` +* Type: string (program path) +* Default: none +* Environment: `CARGO_TARGET__LINKER` + +Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the +`` is being compiled for. By default, the linker is not overridden. + +##### `target..runner` +* Type: string or array of strings (program path and args) +* Default: none +* Environment: `CARGO_TARGET__RUNNER` + +If a runner is provided, executables for the target `` will be +executed by invoking the specified runner with the actual executable passed as +an argument. This applies to [`cargo run`], [`cargo test`] and [`cargo bench`] +commands. By default, compiled executables are executed directly. + +The value may be an array of strings like `['/path/to/program', 'somearg']` or +a space-separated string like `'/path/to/program somearg'`. The arguments will +be passed to the runner with the executable to run as the last argument. If +the runner program does not have path separators, it will search `PATH` for +the runner executable. + +##### `target..runner` + +This is similar to the [target runner](#targettriplerunner), but using +a [`cfg()` expression]. If both a `` and `` runner match, +the `` will take precedence. It is an error if more than one +`` runner matches the current target. + +##### `target..rustflags` +* Type: string or array of strings +* Default: none +* Environment: `CARGO_TARGET__RUSTFLAGS` + +Passes a set of custom flags to the compiler for this ``. The value +may be a array of strings or a space-separated string. + +See [`build.rustflags`](#buildrustflags) for more details on the different +ways to specific extra flags. + +##### `target..rustflags` + +This is similar to the [target rustflags](#targettriplerustflags), but +using a [`cfg()` expression]. If several `` and `` entries +match the current target, the flags are joined together. + +##### `target..` + +The links sub-table provides a way to [override a build script]. When +specified, the build script for the given `links` library will not be +run, and the given values will be used instead. + +```toml +[target.x86_64-unknown-linux-gnu.foo] +rustc-link-lib = ["foo"] +rustc-link-search = ["/path/to/foo"] +rustc-flags = "-L /some/path" +rustc-cfg = ['key="value"'] +rustc-env = {key = "value"} +rustc-cdylib-link-arg = ["…"] +metadata_key1 = "value" +metadata_key2 = "value" +``` + +#### `[term]` + +The `[term]` table controls terminal output and interaction. + +##### `term.verbose` +* Type: boolean +* Default: false +* Environment: `CARGO_TERM_VERBOSE` + +Controls whether or not extra detailed messages are displayed by Cargo. + +Specifying the `--quiet` flag will override and disable verbose output. +Specifying the `--verbose` flag will override and force verbose output. + +##### `term.color` +* Type: string +* Default: "auto" +* Environment: `CARGO_TERM_COLOR` + +Controls whether or not colored output is used in the terminal. Possible values: + +* `auto` (default): Automatically detect if color support is available on the + terminal. +* `always`: Always display colors. +* `never`: Never display colors. + +Can be overridden with the `--color` command-line option. + + +[`cargo bench`]: ../commands/cargo-bench.md [`cargo login`]: ../commands/cargo-login.md +[`cargo new`]: ../commands/cargo-new.md [`cargo publish`]: ../commands/cargo-publish.md +[`cargo run`]: ../commands/cargo-run.md +[`cargo rustc`]: ../commands/cargo-rustc.md +[`cargo test`]: ../commands/cargo-test.md +[`cargo rustdoc`]: ../commands/cargo-rustdoc.md +[`cargo install`]: ../commands/cargo-install.md [env]: environment-variables.md -[source]: source-replacement.md +[`cfg()` expression]: ../../reference/conditional-compilation.html +[build scripts]: build-scripts.md +[`-C linker`]: ../../rustc/codegen-options/index.md#linker +[override a build script]: build-scripts.md#overriding-build-scripts +[toml]: https://github.com/toml-lang/toml +[incremental compilation]: profiles.md#incremental +[profile]: profiles.md +[libcurl format]: https://ec.haxx.se/usingcurl-proxies.html +[source replacement]: source-replacement.md +[revision]: https://git-scm.com/docs/gitrevisions +[registries]: registries.md +[crates.io]: https://crates.io/ diff --git a/src/doc/src/reference/environment-variables.md b/src/doc/src/reference/environment-variables.md index fda387bad34..df057fa8766 100644 --- a/src/doc/src/reference/environment-variables.md +++ b/src/doc/src/reference/environment-variables.md @@ -9,38 +9,135 @@ with them: You can override these environment variables to change Cargo's behavior on your system: -* `CARGO_HOME` — Cargo maintains a local cache of the registry index and of git - checkouts of crates. By default these are stored under `$HOME/.cargo`, but - this variable overrides the location of this directory. Once a crate is cached - it is not removed by the clean command. +* `CARGO_HOME` — Cargo maintains a local cache of the registry index and of + git checkouts of crates. By default these are stored under `$HOME/.cargo` + (`%USERPROFILE%\.cargo` on Windows), but this variable overrides the + location of this directory. Once a crate is cached it is not removed by the + clean command. For more details refer to the [guide](../guide/cargo-home.md). * `CARGO_TARGET_DIR` — Location of where to place all generated artifacts, - relative to the current working directory. + relative to the current working directory. See [`build.target-dir`] to set + via config. * `RUSTC` — Instead of running `rustc`, Cargo will execute this specified - compiler instead. + compiler instead. See [`build.rustc`] to set via config. * `RUSTC_WRAPPER` — Instead of simply running `rustc`, Cargo will execute this specified wrapper instead, passing as its commandline arguments the rustc invocation, with the first argument being `rustc`. Useful to set up a build - cache tool such as `sccache`. + cache tool such as `sccache`. See [`build.rustc-wrapper`] to set via config. * `RUSTDOC` — Instead of running `rustdoc`, Cargo will execute this specified - `rustdoc` instance instead. + `rustdoc` instance instead. See [`build.rustdoc`] to set via config. * `RUSTDOCFLAGS` — A space-separated list of custom flags to pass to all `rustdoc` - invocations that Cargo performs. In contrast with `cargo rustdoc`, this is - useful for passing a flag to *all* `rustdoc` instances. + invocations that Cargo performs. In contrast with [`cargo rustdoc`], this is + useful for passing a flag to *all* `rustdoc` instances. See + [`build.rustdocflags`] for some more ways to set flags. * `RUSTFLAGS` — A space-separated list of custom flags to pass to all compiler - invocations that Cargo performs. In contrast with `cargo rustc`, this is - useful for passing a flag to *all* compiler instances. -* `CARGO_INCREMENTAL` — If this is set to 1 then Cargo will force incremental - compilation to be enabled for the current compilation, and when set to 0 it + invocations that Cargo performs. In contrast with [`cargo rustc`], this is + useful for passing a flag to *all* compiler instances. See + [`build.rustflags`] for some more ways to set flags. +* `CARGO_INCREMENTAL` — If this is set to 1 then Cargo will force [incremental + compilation] to be enabled for the current compilation, and when set to 0 it will force disabling it. If this env var isn't present then cargo's defaults - will otherwise be used. + will otherwise be used. See also [`build.incremental`] config value. * `CARGO_CACHE_RUSTC_INFO` — If this is set to 0 then Cargo will not try to cache compiler version information. +* `CARGO_NAME` — The author name to use for [`cargo new`]. +* `CARGO_EMAIL` — The author email to use for [`cargo new`]. +* `HTTPS_PROXY` or `https_proxy` or `http_proxy` — The HTTP proxy to use, see + [`http.proxy`] for more detail. +* `HTTP_TIMEOUT` — The HTTP timeout in seconds, see [`http.timeout`] for more + detail. +* `TERM` — If this is set to `dumb`, it disables the progress bar. +* `BROWSER` — The web browser to execute to open documentation with [`cargo + doc`]'s' `--open` flag. -Note that Cargo will also read environment variables for `.cargo/config` -configuration values, as described in [that documentation][config-env] +#### Configuration environment variables +Cargo reads environment variables for configuration values. See the +[configuration chapter][config-env] for more details. In summary, the +supported environment variables are: + +* `CARGO_ALIAS_` — Command aliases, see [`alias`]. +* `CARGO_BUILD_JOBS` — Number of parallel jobs, see [`build.jobs`]. +* `CARGO_BUILD_RUSTC` — The `rustc` executable, see [`build.rustc`]. +* `CARGO_BUILD_RUSTC_WRAPPER` — The `rustc` wrapper, see [`build.rustc-wrapper`]. +* `CARGO_BUILD_RUSTDOC` — The `rustdoc` executable, see [`build.rustdoc`]. +* `CARGO_BUILD_TARGET` — The default target platform, see [`build.target`]. +* `CARGO_BUILD_TARGET_DIR` — The default output directory, see [`build.target-dir`]. +* `CARGO_BUILD_RUSTFLAGS` — Extra `rustc` flags, see [`build.rustflags`]. +* `CARGO_BUILD_RUSTDOCFLAGS` — Extra `rustdoc` flags, see [`build.rustdocflags`]. +* `CARGO_BUILD_INCREMENTAL` — Incremental compilation, see [`build.incremental`]. +* `CARGO_BUILD_DEP_INFO_BASEDIR` — Dep-info relative directory, see [`build.dep-info-basedir`]. +* `CARGO_BUILD_PIPELINING` — Whether or not to use `rustc` pipelining, see [`build.pipelining`]. +* `CARGO_CARGO_NEW_NAME` — The author name to use with [`cargo new`], see [`cargo-new.name`]. +* `CARGO_CARGO_NEW_EMAIL` — The author email to use with [`cargo new`], see [`cargo-new.email`]. +* `CARGO_CARGO_NEW_VCS` — The default source control system with [`cargo new`], see [`cargo-new.vcs`]. +* `CARGO_HTTP_DEBUG` — Enables HTTP debugging, see [`http.debug`]. +* `CARGO_HTTP_PROXY` — Enables HTTP proxy, see [`http.proxy`]. +* `CARGO_HTTP_TIMEOUT` — The HTTP timeout, see [`http.timeout`]. +* `CARGO_HTTP_CAINFO` — The TLS certificate Certificate Authority file, see [`http.cainfo`]. +* `CARGO_HTTP_CHECK_REVOKE` — Disables TLS certificate revocation checks, see [`http.check-revoke`]. +* `CARGO_HTTP_SSL_VERSION` — The TLS version to use, see [`http.ssl-version`]. +* `CARGO_HTTP_LOW_SPEED_LIMIT` — The HTTP low-speed limit, see [`http.low-speed-limit`]. +* `CARGO_HTTP_MULTIPLEXING` — Whether HTTP/2 multiplexing is used, see [`http.multiplexing`]. +* `CARGO_HTTP_USER_AGENT` — The HTTP user-agent header, see [`http.user-agent`]. +* `CARGO_INSTALL_ROOT` — The default directory for [`cargo install`], see [`install.root`]. +* `CARGO_NET_RETRY` — Number of times to retry network errors, see [`net.retry`]. +* `CARGO_NET_GIT_FETCH_WITH_CLI` — Enables the use of the `git` executable to fetch, see [`net.git-fetch-with-cli`]. +* `CARGO_NET_OFFLINE` — Offline mode, see [`net.offline`]. +* `CARGO_REGISTRIES__INDEX` — URL of a registry index, see [`registries..index`]. +* `CARGO_REGISTRIES__TOKEN` — Authentication token of a registry, see [`registries..token`]. +* `CARGO_REGISTRY_DEFAULT` — Default registry for the `--registry` flag, see [`registry.default`]. +* `CARGO_REGISTRY_TOKEN` — Authentication token for [crates.io], see [`registry.token`]. +* `CARGO_TARGET__LINKER` — The linker to use, see [`target..linker`]. +* `CARGO_TARGET__RUNNER` — The executable runner, see [`target..runner`]. +* `CARGO_TARGET__RUSTFLAGS` — Extra `rustc` flags for a target, see [`target..rustflags`]. +* `CARGO_TERM_VERBOSE` — The default terminal verbosity, see [`term.verbose`]. +* `CARGO_TERM_COLOR` — The default color mode, see [`term.color`]. + +[`cargo doc`]: ../commands/cargo-doc.md +[`cargo install`]: ../commands/cargo-install.md +[`cargo new`]: ../commands/cargo-new.md +[`cargo rustc`]: ../commands/cargo-rustc.md [config-env]: config.md#environment-variables +[crates.io]: https://crates.io/ +[incremental compilation]: profiles.md#incremental +[`alias`]: config.md#alias +[`build.jobs`]: config.md#buildjobs +[`build.rustc`]: config.md#buildrustc +[`build.rustc-wrapper`]: config.md#buildrustc-wrapper +[`build.rustdoc`]: config.md#buildrustdoc +[`build.target`]: config.md#buildtarget +[`build.target-dir`]: config.md#buildtarget-dir +[`build.rustflags`]: config.md#buildrustflags +[`build.rustdocflags`]: config.md#buildrustdocflags +[`build.incremental`]: config.md#buildincremental +[`build.dep-info-basedir`]: config.md#builddep-info-basedir +[`build.pipelining`]: config.md#buildpipelining +[`cargo-new.name`]: config.md#cargo-newname +[`cargo-new.email`]: config.md#cargo-newemail +[`cargo-new.vcs`]: config.md#cargo-newvcs +[`http.debug`]: config.md#httpdebug +[`http.proxy`]: config.md#httpproxy +[`http.timeout`]: config.md#httptimeout +[`http.cainfo`]: config.md#httpcainfo +[`http.check-revoke`]: config.md#httpcheck-revoke +[`http.ssl-version`]: config.md#httpssl-version +[`http.low-speed-limit`]: config.md#httplow-speed-limit +[`http.multiplexing`]: config.md#httpmultiplexing +[`http.user-agent`]: config.md#httpuser-agent +[`install.root`]: config.md#installroot +[`net.retry`]: config.md#netretry +[`net.git-fetch-with-cli`]: config.md#netgit-fetch-with-cli +[`net.offline`]: config.md#netoffline +[`registries..index`]: config.md#registriesnameindex +[`registries..token`]: config.md#registriesnametoken +[`registry.default`]: config.md#registrydefault +[`registry.token`]: config.md#registrytoken +[`target..linker`]: config.md#targettriplelinker +[`target..runner`]: config.md#targettriplerunner +[`target..rustflags`]: config.md#targettriplerustflags +[`term.verbose`]: config.md#termverbose +[`term.color`]: config.md#termcolor ### Environment variables Cargo sets for crates @@ -123,14 +220,24 @@ let out_dir = env::var("OUT_DIR").unwrap(); where `` is the name of the feature uppercased and having `-` translated to `_`. * `CARGO_CFG_` - For each [configuration option][configuration] of the - package being built, this environment variable will - contain the value of the configuration, where `` is - the name of the configuration uppercased and having `-` - translated to `_`. - Boolean configurations are present if they are set, and - not present otherwise. - Configurations with multiple values are joined to a - single variable with the values delimited by `,`. + package being built, this environment variable will contain the value of the + configuration, where `` is the name of the configuration uppercased and + having `-` translated to `_`. Boolean configurations are present if they are + set, and not present otherwise. Configurations with multiple values are + joined to a single variable with the values delimited by `,`. This includes + values built-in to the compiler (which can be seen with `rustc --print=cfg`) + and values set by build scripts and extra flags passed to `rustc` (such as + those defined in `RUSTFLAGS`). Some examples of what these variables are: + * `CARGO_CFG_UNIX` — Set on [unix-like platforms]. + * `CARGO_CFG_WINDOWS` — Set on [windows-like platforms]. + * `CARGO_CFG_TARGET_FAMILY=unix` — The [target family], either `unix` or `windows`. + * `CARGO_CFG_TARGET_OS=macos` — The [target operating system]. + * `CARGO_CFG_TARGET_ARCH=x86_64` — The CPU [target architecture]. + * `CARGO_CFG_TARGET_VENDOR=apple` — The [target vendor]. + * `CARGO_CFG_TARGET_ENV=gnu` — The [target environment] ABI. + * `CARGO_CFG_TARGET_POINTER_WIDTH=64` — The CPU [pointer width]. + * `CARGO_CFG_TARGET_ENDIAN=little` — The CPU [target endianess]. + * `CARGO_CFG_TARGET_FEATURE=mmx,sse` — List of CPU [target features] enabled. * `OUT_DIR` - the folder in which all output should be placed. This folder is inside the build directory for the package being built, and it is unique for the package in question. @@ -161,6 +268,16 @@ let out_dir = env::var("OUT_DIR").unwrap(); about [cargo configuration][cargo-config] for more information. +[unix-like platforms]: ../../reference/conditional-compilation.html#unix-and-windows +[windows-like platforms]: ../../reference/conditional-compilation.html#unix-and-windows +[target family]: ../../reference/conditional-compilation.html#target_family +[target operating system]: ../../reference/conditional-compilation.html#target_os +[target architecture]: ../../reference/conditional-compilation.html#target_arch +[target vendor]: ../../reference/conditional-compilation.html#target_vendor +[target environment]: ../../reference/conditional-compilation.html#target_env +[pointer width]: ../../reference/conditional-compilation.html#target_pointer_width +[target endianess]: ../../reference/conditional-compilation.html#target_endian +[target features]: ../../reference/conditional-compilation.html#target_feature [links]: build-scripts.md#the-links-manifest-key [configuration]: ../../reference/conditional-compilation.html [jobserver]: https://www.gnu.org/software/make/manual/html_node/Job-Slots.html diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md index 795edebe7ef..67c05bc1fb2 100644 --- a/src/doc/src/reference/profiles.md +++ b/src/doc/src/reference/profiles.md @@ -165,11 +165,11 @@ Incremental compilation is only used for workspace members and "path" dependencies. The incremental value can be overridden globally with the `CARGO_INCREMENTAL` -[environment variable] or the `build.incremental` [config variable]. +[environment variable] or the [`build.incremental`] config variable. [`-C incremental` flag]: ../../rustc/codegen-options/index.html#incremental [environment variable]: environment-variables.md -[config variable]: config.md +[`build.incremental`]: config.md#buildincremental #### codegen-units