Module context

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 to ConfigRelativePath, 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

BuildTargetConfig

Configuration for build.target.

CargoBuildConfig

CargoFutureIncompatConfig

CargoHttpConfig

CargoNetConfig

CargoResolverConfig

CargoSshConfig

ConfigError

Internal error for serde errors.

ConfigKey

Key for a configuration variable.

ConfigRelativePath

Use with the get API to fetch a string that will be converted to a PathBuf. Relative paths are converted to absolute paths based on the location of the config file.

CredentialCacheValue

A previously generated authentication token and the data needed to determine if it can be reused.

EnvConfigValue

GlobalContext

Configuration information for cargo. This is not specific to a build, it is information relating to cargo itself.

MissingFieldError 🔒

PathAndArgs

A config type that is a program to run.

ProgressConfig

SslVersionConfigRange

StringList

A type to deserialize a list of strings from a toml file.

TargetCfgConfig

Config definition of a [target.'cfg(…)'] table.

TargetConfig

Config definition of a [target] table or [host].

TermConfig

Value

A type which can be deserialized as a configuration value which records where it was deserialized from.

Enums

BuildTargetConfigInner 🔒

CargoFutureIncompatFrequencyConfig

ConfigValue

Definition

Location where a config value is defined.

EnvConfigValueInner 🔒

FeatureUnification

IncompatibleRustVersions

JobsConfig

Configuration for jobs in build section. There are two ways to configure: An integer or a simple string expression.

ProgressWhen

SslVersionConfig

Configuration for ssl-version in http section There are two ways to configure:

Tool 🔒

WarningHandling

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

Type Aliases

EnvConfig

OptValue