## Module context

Source
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 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.

## §Config schemas

Configuration schemas are defined in the `schema` module.

### §Config deserialization

Cargo uses a two-layer deserialization approach:

1. External sources → `ConfigValue` — Configuration files, environment variables, and CLI `--config` arguments are parsed into `ConfigValue` instances via `ConfigValue::from_toml`. These parsed results are stored in `GlobalContext`.

2. `ConfigValue` → Target types — The `GlobalContext::get` method uses a custom serde deserializer to convert `ConfigValue` instances to the caller’s desired type. Precedence between `ConfigValue` sources is resolved during retrieval based on `Definition` priority. See the top-level documentation of the `de` module for more.

### §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.)

## Modules§

config_value 🔒
  `ConfigValue` represents Cargo configuration values loaded from TOML.
de 🔒
  Deserialization for converting `ConfigValue` instances to target types.
environment 🔒
  Encapsulates snapshotting of environment variables.
error 🔒
key 🔒
path 🔒
schema 🔒
  Cargo configuration schemas.
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`.
CargoBuildAnalysis
  Metrics collection for build analysis.
CargoBuildConfig
  The `[build]` table.
CargoFutureIncompatConfig
  The `[future-incompat-report]` stable
CargoHttpConfig
  The `[http]` table.
CargoNetConfig
  The `[net]` table.
CargoResolverConfig
  The `[resolver]` table.
CargoSshConfig
ConfigError
  Internal error for serde errors.
ConfigInclude 🔒
  Represents a config-include value in the configuration.
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
  Configuration value for environment variables in `[env]` section.
GlobalContext
  Configuration information for cargo. This is not specific to a build, it is information relating to cargo itself.
PathAndArgs
  A config type that is a program to run.
ProgressConfig
  The `term.progress` configuration.
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
  The `[term]` table.
Value
  A type which can be deserialized as a configuration value which records where it was deserialized from.

## Enums§

BracketType
CargoFutureIncompatFrequencyConfig
ConfigValue
  Similar to [`toml::Value`] but includes the source location where it is defined.
Definition
  Location where a config value is defined.
FeatureUnification
IncompatibleRustVersions
JobsConfig
  Configuration for `jobs` in `build` section. There are two ways to configure: An integer or a simple string expression.
ProgressWhen
ResolveTemplateError
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.

## Constants§

TOP_LEVEL_CONFIG_KEYS

## Functions§

disables_multiplexing_for_bad_curl 🔒
  Disable HTTP/2 multiplexing for some broken versions of libcurl.
homedir
parse_document 🔒
save_credentials
toml_dotted_keys 🔒

## Type Aliases§

EnvConfig
OptValue