t = "test"
r = "run"
rr = "run --release"
+recursive_example = "rr --example recursions"
space_example = ["run", "--release", "--", "\"command list\""]
[build]
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
[doc]
browser = "chromium" # browser to use with `cargo doc --open`,
metadata_key2 = "value"
[term]
+quiet = false # whether cargo output is quiet
verbose = false # whether cargo provides verbose output
color = 'auto' # whether cargo colorizes output
progress.when = 'auto' # whether cargo shows progress bar
In addition to the system above, Cargo recognizes a few other specific
[environment variables][env].
+### Command-line overrides
+
+Cargo also accepts arbitrary configuration overrides through the
+`--config` command-line option. The argument should be in TOML syntax of
+`KEY=VALUE`:
+
+```console
+cargo --config net.git-fetch-with-cli=true fetch
+```
+
+The `--config` option may be specified multiple times, in which case the
+values are merged in left-to-right order, using the same merging logic
+that is used when multiple configuration files apply. Configuration
+values specified this way take precedence over environment variables,
+which take precedence over configuration files.
+
+Some examples of what it looks like using Bourne shell syntax:
+
+```console
+# Most shells will require escaping.
+cargo --config http.proxy=\"http://example.com\" …
+
+# Spaces may be used.
+cargo --config "net.git-fetch-with-cli = true" …
+
+# TOML array example. Single quotes make it easier to read and write.
+cargo --config 'build.rustdocflags = ["--html-in-header", "header.html"]' …
+
+# Example of a complex TOML key.
+cargo --config "target.'cfg(all(target_arch = \"arm\", target_os = \"none\"))'.runner = 'my-runner'" …
+
+# Example of overriding a profile setting.
+cargo --config profile.dev.package.image.opt-level=3 …
+```
+
+The `--config` option can also be used to pass paths to extra
+configuration files that Cargo should use for a specific invocation.
+Options from configuration files loaded this way follow the same
+precedence rules as other options specified directly with `--config`.
+
### 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.
+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.
+
+In particular, rules are:
+
+* For environment variables, paths are relative to the current working directory.
+* For config values loaded directly from the [`--config KEY=VALUE`](#command-line-overrides) option,
+ paths are relative to the current working directory.
+* For config files, paths are relative to the parent directory of the directory where the config files were defined,
+ no matter those files are from either the [hierarchical probing](#hierarchical-structure)
+ or the [`--config <path>`](#command-line-overrides) option.
+
+> **Note:** To maintain consistency with existing `.cargo/config.toml` probing behavior,
+> it is by design that a path in a config file passed via `--config <path>`
+> is also relative to two levels up from the config file itself.
+>
+> To avoid unexpected results, the rule of thumb is putting your extra config files
+> at the same level of discovered `.cargo/config.toml` in your porject.
+> For instance, given a project `/my/project`,
+> it is recommended to put config files under `/my/project/.cargo`
+> or a new directory at the same level, such as `/my/project/.config`.
```toml
# Relative path examples.
Aliases are not allowed to redefine existing built-in commands.
+Aliases are recursive:
+
+```toml
+[alias]
+rr = "run --release"
+recursive_example = "rr --example recursions"
+```
+
#### `[build]`
The `[build]` table controls build-time operations and compiler settings.
* Default: number of logical CPUs
* Environment: `CARGO_BUILD_JOBS`
-Sets the maximum number of compiler processes to run in parallel.
+Sets the maximum number of compiler processes to run in parallel. If negative,
+it sets the maximum number of compiler processes to the number of logical CPUs
+plus provided value. Should not be 0.
Can be overridden with the `--jobs` CLI option.
* 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`.
+wrapper is the path to the actual executable to use
+(i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
##### `build.rustc-workspace-wrapper`
* Type: string (program path)
* Environment: `CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER` or `RUSTC_WORKSPACE_WRAPPER`
Sets a wrapper to execute instead of `rustc`, for workspace members only.
-The first argument passed to the wrapper is the path to the actual `rustc`.
+The first argument passed to the wrapper is the path to the actual
+executable to use (i.e., `build.rustc`, if that is set, or `"rustc"` otherwise).
It affects the filename hash so that artifacts produced by the wrapper are cached separately.
##### `build.rustdoc`
Sets the executable to use for `rustdoc`.
##### `build.target`
-* Type: string
+* Type: string or array of strings
* Default: host platform
* Environment: `CARGO_BUILD_TARGET`
-The default target platform triple to compile to.
+The default target platform triples to compile to.
-This may also be a relative path to a `.json` target spec file.
+This allows passing either a string or an array of strings. Each string value
+is a target platform triple. The selected build targets will be built for each
+of the selected architectures.
+
+The string value may also be a relative path to a `.json` target spec file.
Can be overridden with the `--target` CLI option.
+```toml
+[build]
+target = ["x86_64-unknown-linux-gnu", "i686-unknown-linux-gnu"]
+```
+
##### `build.target-dir`
* Type: string (path)
* Default: "target"
##### `build.rustflags`
* Type: string or array of strings
* Default: none
-* Environment: `CARGO_BUILD_RUSTFLAGS` or `RUSTFLAGS`
+* Environment: `CARGO_BUILD_RUSTFLAGS` or `CARGO_ENCODED_RUSTFLAGS` or `RUSTFLAGS`
-Extra command-line flags to pass to `rustc`. The value may be a array of
+Extra command-line flags to pass to `rustc`. The value may be an array of
strings or a space-separated string.
-There are three mutually exclusive sources of extra flags. They are checked in
+There are four 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`
+1. `CARGO_ENCODED_RUSTFLAGS` environment variable.
+2. `RUSTFLAGS` environment variable.
+3. All matching `target.<triple>.rustflags` and `target.<cfg>.rustflags`
config entries joined together.
-3. `build.rustflags` config value.
+4. `build.rustflags` config value.
Additional flags may also be passed with the [`cargo rustc`] command.
are building for the host, pass `--target` with the host triple.
It is not recommended to pass in flags that Cargo itself usually manages. For
-example, the flags driven by [profiles] are best handled by setting the
+example, the flags driven by [profiles](profiles.md) are best handled by setting the
appropriate profile setting.
> **Caution**: Due to the low-level nature of passing flags directly to the
##### `build.rustdocflags`
* Type: string or array of strings
* Default: none
-* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `RUSTDOCFLAGS`
+* Environment: `CARGO_BUILD_RUSTDOCFLAGS` or `CARGO_ENCODED_RUSTDOCFLAGS` or `RUSTDOCFLAGS`
-Extra command-line flags to pass to `rustdoc`. The value may be a array of
+Extra command-line flags to pass to `rustdoc`. The value may be an array of
strings or a space-separated string.
-There are two mutually exclusive sources of extra flags. They are checked in
+There are three 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.
+1. `CARGO_ENCODED_RUSTDOCFLAGS` environment variable.
+2. `RUSTDOCFLAGS` environment variable.
+3. `build.rustdocflags` config value.
Additional flags may also be passed with the [`cargo rustdoc`] command.
* 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
+to use the value from the [profile](profiles.md#incremental). Otherwise this overrides the setting of
all profiles.
The `CARGO_INCREMENTAL` environment variable can be set to `1` to force enable
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.
+This option is deprecated and unused. Cargo always has pipelining enabled.
#### `[doc]`
##### `doc.browser`
-* Type: string or array of strings ([program path and args])
+* Type: string or array of strings ([program path with args])
* Default: `BROWSER` environment variable, or, if that is missing,
opening the link in a system specific way
`<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])
+* Type: string or array of strings ([program path with args])
* Default: none
* Environment: `CARGO_TARGET_<triple>_RUNNER`
* 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.
+may be an array of strings or a space-separated string.
See [`build.rustflags`](#buildrustflags) for more details on the different
ways to specific extra flags.
The `[term]` table controls terminal output and interaction.
+##### `term.quiet`
+* Type: boolean
+* Default: false
+* Environment: `CARGO_TERM_QUIET`
+
+Controls whether or not log messages are displayed by Cargo.
+
+Specifying the `--quiet` flag will override and force quiet output.
+Specifying the `--verbose` flag will override and disable quiet output.
+
##### `term.verbose`
* Type: boolean
* Default: false
[override a build script]: build-scripts.md#overriding-build-scripts
[toml]: https://toml.io/
[incremental compilation]: profiles.md#incremental
-[profile]: profiles.md
[program path with args]: #executable-paths-with-arguments
-[libcurl format]: https://ec.haxx.se/usingcurl-proxies.html
+[libcurl format]: https://everything.curl.dev/libcurl/proxies#proxy-types
[source replacement]: source-replacement.md
[revision]: https://git-scm.com/docs/gitrevisions
[registries]: registries.md
projects / cargo.git / blobdiff