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: 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 [crate::config::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 [ConfigReader::get] for the typed lookup API.

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.$TUPLE 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.)

Re-exports

use cargo_util::collections::HashMap; 🔒

use cargo_util::collections::HashSet; 🔒

use std::borrow::Cow; 🔒

use std::env; 🔒

use std::env; 🔒

use std::ffi::OsStr; 🔒

use std::ffi::OsString; 🔒

use std::fs::File; 🔒

use std::io::SeekFrom; 🔒

use std::path::Path; 🔒

use std::path::PathBuf; 🔒

use std::sync::Arc; 🔒

use std::sync::LazyLock; 🔒

use std::sync::Mutex; 🔒

use std::sync::MutexGuard; 🔒

use std::sync::OnceLock; 🔒

use std::time::Instant; 🔒

use self::ConfigValue as CV; 🔒

use crate::ops::RegistryCredentialConfig; 🔒

use crate::sources::CRATES_IO_INDEX; 🔒

use crate::sources::CRATES_IO_REGISTRY; 🔒

use crate::util::OnceExt as _; 🔒

use crate::util::VersionReqMatchMode; 🔒

use crate::util::cache_lock::CacheLock; 🔒

use crate::util::cache_lock::CacheLockMode; 🔒

use crate::util::cache_lock::CacheLocker; 🔒

use crate::util::errors::CargoResult; 🔒

use crate::util::network::http::HandleConfiguration; 🔒

use crate::util::network::http::configure_http_handle; 🔒

use crate::util::network::http::http_handle; 🔒

use crate::util::network::http_async; 🔒

use crate::util::restricted_names::is_glob_pattern; 🔒

use crate::util::CanonicalUrl; 🔒

use crate::util::closest_msg; 🔒

use crate::util::internal; 🔒

use crate::util::Filesystem; 🔒

use crate::util::IntoUrl; 🔒

use crate::util::IntoUrlWithBase; 🔒

use crate::util::Rustc; 🔒

use crate::workspace::global_cache_tracker::DeferredGlobalLastUse; 🔒

use crate::workspace::global_cache_tracker::GlobalCacheTracker; 🔒

use crate::workspace::CliUnstable; 🔒

use crate::workspace::SourceId; 🔒

use crate::workspace::Workspace; 🔒

use crate::workspace::WorkspaceRootConfig; 🔒

use crate::workspace::features; 🔒

use anyhow::Context as _; 🔒

use anyhow::anyhow; 🔒

use anyhow::bail; 🔒

use anyhow::format_err; 🔒

use cargo_credential::Secret; 🔒

use cargo_util::paths; 🔒

use cargo_util_schemas::manifest::RegistryName; 🔒

use cargo_util_terminal::report::Level; 🔒

use cargo_util_terminal::Shell; 🔒

use cargo_util_terminal::Verbosity; 🔒

use curl::easy::Easy; 🔒

use itertools::Itertools; 🔒

use serde::Deserialize; 🔒

use serde::Deserialize; 🔒

use serde::de::IntoDeserializer as _; 🔒

use time::OffsetDateTime; 🔒

use toml_edit::Item; 🔒

use url::Url; 🔒

use crate::config::ConfigReader; 🔒

use crate::config::Env; 🔒

pub use path::BracketType;

pub use path::ConfigRelativePathResolveExt;

pub use path::ResolveTemplateError;

pub use target::TargetCfgConfig;

pub use target::TargetConfig;

use std::io::prelude::*; 🔒

Modules

path 🔒

target 🔒

Structs

BuildStdConfig

Configuration for build.build-std.

BuildTargetConfig

Configuration for build.target.

CargoBuildAnalysis

Metrics collection for build analysis.

CargoBuildConfig

The [build] table.

CargoCacheConfig

CargoFutureIncompatConfig

The [future-incompat-report] stable

CargoHttpConfig

The [http] table.

CargoNetConfig

The [net] table.

CargoNewConfig

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.

ConfigStore

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.

GlobalCleanConfig

Cache cleaning settings from the cache.global-clean config table.

GlobalContext

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

GlobalRegistryConfig

The [registry] table, which has more keys than the [registries.NAME] tables.

PathAndArgs

A config type that is a program to run.

ProgressConfig

The term.progress configuration.

RegistryConfig

[registries.NAME] tables.

RegistryCredential

Credentials for a registry.

RustdocExternMap

A map of registry names to URLs where documentations are hosted. This is for unstable feature -Zrustdoc-map.

SourceConfigDef

Definition of a source in a config file.

SslVersionConfigRange

StringList

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

TermConfig

The [term] table.

Value

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

Enums

BuildStdCrates

Which standard library crates to build. Valid values are “core”, “alloc”, “std”, or an array of crate names

BuildStdWhen

When to build the standard library.

CargoFutureIncompatFrequencyConfig

ConfigValue

Similar to [toml::Value] but includes the source location where it is defined.

Definition

Location where a config value is defined.

DefinitionKind

The kind of source where a config value is defined.

FeatureUnification

FingerprintMethod

IncompatiblePublishAge

IncompatibleRustVersions

JobsConfig

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

ProgressWhen

RustdocExternMode

Mode used for std. This is for unstable feature -Zrustdoc-map.

SslVersionConfig

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

Tool 🔒

VersionControl

WarningHandling

Whether warnings should warn, be allowed, or cause an error.

Constants

TOP_LEVEL_CONFIG_KEYS

Functions

disables_multiplexing_for_bad_curl 🔒

Disable HTTP/2 multiplexing for some broken versions of libcurl.

homedir

registry_config_uncached 🔒

registry_name 🔒

save_credentials

toml_dotted_keys 🔒

Type Aliases

EnvConfig

OptValue