itsscb/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2025-09-25 11:14:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Auto merge of #7650 - ehuss:config-docs, r=Eh2406

Browse Source 
Update config and environment variable docs.

Various updates to try to clarify and expand the documentation for config variables and environment variables.

Closes #4041
Closes #7610
Closes #7571
Closes #5780
Closes #5690
This commit is contained in:
bors 2019-12-03 03:12:27 +00:00
commit 6b4dd239a4
4 changed files with 916 additions and 193 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
src/doc/src/reference/build-scripts.md
View File

@ -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

917
src/doc/src/reference/config.md
View File

@ -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.
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 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
### Configuration keys
All of the following keys are optional, and their defaults are listed as their
value unless otherwise noted.
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"]
paths = ["/path/to/override"] # path dependency overrides
[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
[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
[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`
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
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
[term]
verbose = false # whether cargo provides verbose output
color = 'auto' # whether cargo colorizes output
# 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
# Alias cargo commands. The first 4 aliases are built in. If your
# command requires grouped whitespace use the list format.
[alias]
[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`
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
incremental = true # whether or not to enable incremental compilation
dep-info-basedir = "…" # path for the base directory for targets in depfiles
pipelining = true # rustc pipelining
[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
[net]
retry = 2 # network retries
git-fetch-with-cli = true # use the `git` executable for git operations
offline = false # do not access the network
[registries.<name>] # 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.<name>] # 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.<triple>]
linker = "…" # linker to use
runner = "…" # wrapper to run executables
rustflags = ["…", "…"] # custom flags for `rustc`
[target.<cfg>]
runner = "…" # wrapper to run executables
rustflags = ["…", "…"] # custom flags for `rustc`
[target.<triple>.<links>] # `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`.
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 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.
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.<name>]
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_<name>_TOKEN` where `<name>` 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.<triple>` where
the `<triple>` 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_<name>`
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.<triple>.rustflags` and `target.<cfg>.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.<name>.index`
* Type: string (url)
* Default: none
* Environment: `CARGO_REGISTRIES_<name>_INDEX`
Specifies the URL of the git index for the registry.
##### `registries.<name>.token`
* Type: string
* Default: none
* Environment: `CARGO_REGISTRIES_<name>_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.<name>.replace-with`
* Type: string
* Default: none
* Environment: not supported
If set, replace this source with the given named source.
##### `source.<name>.directory`
* Type: string (path)
* Default: none
* Environment: not supported
Sets the path to a directory to use as a directory source.
##### `source.<name>.registry`
* Type: string (url)
* Default: none
* Environment: not supported
Sets the URL to use for a registry source.
##### `source.<name>.local-registry`
* Type: string (path)
* Default: none
* Environment: not supported
Sets the path to a directory to use as a local registry source.
##### `source.<name>.git`
* Type: string (url)
* Default: none
* Environment: not supported
Sets the URL to use for a git repository source.
##### `source.<name>.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.<name>.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.<name>.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 `<triple>` value or the `<cfg>` 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 `<triple>` value is the filename stem.
For example `--target foo/bar.json` would match `[target.bar]`.
##### `target.<triple>.ar`
This option is deprecated and unused.
##### `target.<triple>.linker`
* Type: string (program path)
* Default: none
* Environment: `CARGO_TARGET_<triple>_LINKER`
Specifies the linker which is passed to `rustc` (via [`-C linker`]) when the
`<triple>` is being compiled for. By default, the linker is not overridden.
##### `target.<triple>.runner`
* Type: string or array of strings (program path and args)
* Default: none
* Environment: `CARGO_TARGET_<triple>_RUNNER`
If a runner is provided, executables for the target `<triple>` 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.<cfg>.runner`
This is similar to the [target runner](#targettriplerunner), but using
a [`cfg()` expression]. If both a `<triple>` and `<cfg>` runner match,
the `<triple>` will take precedence. It is an error if more than one
`<cfg>` runner matches the current target.
##### `target.<triple>.rustflags`
* Type: string or array of strings
* Default: none
* Environment: `CARGO_TARGET_<triple>_RUSTFLAGS`
Passes a set of custom flags to the compiler for this `<triple>`. 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.<cfg>.rustflags`
This is similar to the [target rustflags](#targettriplerustflags), but
using a [`cfg()` expression]. If several `<cfg>` and `<triple>` entries
match the current target, the flags are joined together.
##### `target.<triple>.<links>`
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/

167
src/doc/src/reference/environment-variables.md
View File

@ -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_<name>` — 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_<name>_INDEX` — URL of a registry index, see [`registries.<name>.index`].
* `CARGO_REGISTRIES_<name>_TOKEN` — Authentication token of a registry, see [`registries.<name>.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_<triple>_LINKER` — The linker to use, see [`target.<triple>.linker`].
* `CARGO_TARGET_<triple>_RUNNER` — The executable runner, see [`target.<triple>.runner`].
* `CARGO_TARGET_<triple>_RUSTFLAGS` — Extra `rustc` flags for a target, see [`target.<triple>.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.<name>.index`]: config.md#registriesnameindex
[`registries.<name>.token`]: config.md#registriesnametoken
[`registry.default`]: config.md#registrydefault
[`registry.token`]: config.md#registrytoken
[`target.<triple>.linker`]: config.md#targettriplelinker
[`target.<triple>.runner`]: config.md#targettriplerunner
[`target.<triple>.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 `<name>` is the name of the feature uppercased
and having `-` translated to `_`.
* `CARGO_CFG_<cfg>` - For each [configuration option][configuration] of the
package being built, this environment variable will
contain the value of the configuration, where `<cfg>` 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 `<cfg>` 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

4
src/doc/src/reference/profiles.md
View File

@ -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