Expand description
Cargo’s config system.
The GlobalContext
object contains general information about the environment,
and provides access to Cargo’s configuration files.
§Config value API
The primary API for fetching user-defined config values is the
GlobalContext::get
method. It uses serde
to translate config values to a
target type.
There are a variety of helper types for deserializing some common formats:
value::Value
: This type provides access to the location where the config value was defined.ConfigRelativePath
: For a path that is relative to where it is defined.PathAndArgs
: Similar toConfigRelativePath
, but also supports a list of arguments, useful for programs to execute.StringList
: Get a value that is either a list or a whitespace split string.
§Map key recommendations
Handling tables that have arbitrary keys can be tricky, particularly if it
should support environment variables. In general, if possible, the caller
should pass the full key path into the get()
method so that the config
deserializer can properly handle environment variables (which need to be
uppercased, and dashes converted to underscores).
A good example is the [target]
table. The code will request
target.$TRIPLE
and the config system can then appropriately fetch
environment variables like CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER
.
Conversely, it is not possible do the same thing for the cfg()
target
tables (because Cargo must fetch all of them), so those do not support
environment variables.
Try to avoid keys that are a prefix of another with a dash/underscore. For
example build.target
and build.target-dir
. This is OK if these are not
structs/maps, but if it is a struct or map, then it will not be able to
read the environment variable due to ambiguity. (See ConfigMapAccess
for
more details.)
§Internal API
Internally config values are stored with the ConfigValue
type after they
have been loaded from disk. This is similar to the toml::Value
type, but
includes the definition location. The get()
method uses serde to
translate from ConfigValue
and environment variables to the caller’s
desired type.
Modules§
- de 🔒
- Support for deserializing configuration via
serde
- environment 🔒
- Encapsulates snapshotting of environment variables.
- key 🔒
- path 🔒
- target 🔒
- value 🔒
- Deserialization of a
Value<T>
type which tracks where it was deserialized from.
Macros§
- get_
value_ 🔒typed - Helper macro for creating typed access methods.
Structs§
- Build
Target Config - Configuration for
build.target
. - Cargo
Build Config - Cargo
Future Incompat Config - Cargo
Http Config - Cargo
NetConfig - Cargo
Resolver Config - Cargo
SshConfig - Config
Error - Internal error for serde errors.
- Config
Key - Key for a configuration variable.
- Config
Relative Path - Use with the
get
API to fetch a string that will be converted to aPathBuf
. Relative paths are converted to absolute paths based on the location of the config file. - Credential
Cache Value - A previously generated authentication token and the data needed to determine if it can be reused.
- EnvConfig
Value - Global
Context - Configuration information for cargo. This is not specific to a build, it is information relating to cargo itself.
- Missing
Field 🔒Error - Path
AndArgs - A config type that is a program to run.
- Progress
Config - SslVersion
Config Range - String
List - A type to deserialize a list of strings from a toml file.
- Target
CfgConfig - Config definition of a
[target.'cfg(…)']
table. - Target
Config - Config definition of a
[target]
table or[host]
. - Term
Config - Value
- A type which can be deserialized as a configuration value which records where it was deserialized from.
Enums§
- Build
Target 🔒Config Inner - Cargo
Future Incompat Frequency Config - Config
Value - Definition
- Location where a config value is defined.
- EnvConfig
Value 🔒Inner - Feature
Unification - Incompatible
Rust Versions - Jobs
Config - Configuration for
jobs
inbuild
section. There are two ways to configure: An integer or a simple string expression. - Progress
When - SslVersion
Config - Configuration for
ssl-version
inhttp
section There are two ways to configure: - Tool 🔒
- Warning
Handling - Whether warnings should warn, be allowed, or cause an error.
- WhyLoad 🔒
- Indicates why a config value is being loaded.
Functions§
- disables_
multiplexing_ 🔒for_ bad_ curl - Disable HTTP/2 multiplexing for some broken versions of libcurl.
- homedir
- is_
nonmergable_ 🔒list - List of which configuration lists cannot be merged. Instead of merging, these the higher priority list replaces the lower priority list.
- parse_
document 🔒 - progress_
or_ 🔒string - save_
credentials