Struct GlobalContext 

pub struct GlobalContext {

    home_path: Filesystem,
    shell: Mutex<Shell>,
    config: OnceLock<ConfigStore>,
    credentials_config: OnceLock<ConfigStore>,
    cli_config: Option<Vec<String>>,
    cwd: PathBuf,
    search_stop_path: Option<PathBuf>,
    cargo_exe: OnceLock<PathBuf>,
    rustdoc: OnceLock<PathBuf>,
    extra_verbose: bool,
    frozen: bool,
    locked: bool,
    offline: bool,
    jobserver: Option<&'static Client>,
    unstable_flags: CliUnstable,
    unstable_flags_cli: Option<Vec<String>>,
    easy: OnceLock<Mutex<Easy>>,
    crates_io_source_id: OnceLock<SourceId>,
    cache_rustc_info: bool,
    invocation_instant: Instant,
    invocation_time: Timestamp,
    target_dir: Option<Filesystem>,
    env: Env,
    updated_sources: Mutex<HashSet<SourceId>>,
    credential_cache: Mutex<HashMap<CanonicalUrl, CredentialCacheValue>>,
    registry_config: Mutex<HashMap<SourceId, Option<RegistryConfig>>>,
    package_cache_lock: CacheLocker,
    http_config: OnceLock<CargoHttpConfig>,
    http_async: OnceLock<Client>,
    future_incompat_config: OnceLock<CargoFutureIncompatConfig>,
    net_config: OnceLock<CargoNetConfig>,
    build_config: OnceLock<CargoBuildConfig>,
    target_cfgs: OnceLock<Vec<(String, TargetCfgConfig)>>,
    doc_extern_map: OnceLock<RustdocExternMap>,
    progress_config: ProgressConfig,
    env_config: OnceLock<Arc<HashMap<String, OsString>>>,
    pub nightly_features_allowed: bool,
    ws_roots: Mutex<HashMap<PathBuf, WorkspaceRootConfig>>,
    global_cache_tracker: OnceLock<Mutex<GlobalCacheTracker>>,
    deferred_global_last_use: OnceLock<Mutex<DeferredGlobalLastUse>>,
}

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

Fields

home_path: Filesystem

The location of the user’s Cargo home directory. OS-dependent.

shell: Mutex<Shell>

Information about how to write messages to the shell

config: OnceLock<ConfigStore>

A collection of configuration options

credentials_config: OnceLock<ConfigStore>

A collection of configuration options from the credentials file

cli_config: Option<Vec<String>>

CLI config values, passed in via configure.

cwd: PathBuf

The current working directory of cargo

search_stop_path: Option<PathBuf>

Directory where config file searching should stop (inclusive).

cargo_exe: OnceLock<PathBuf>

The location of the cargo executable (path to current process)

rustdoc: OnceLock<PathBuf>

The location of the rustdoc executable

extra_verbose: bool

Whether we are printing extra verbose messages

frozen: bool

frozen is the same as locked, but additionally will not access the network to determine if the lock file is out-of-date.

locked: bool

locked is set if we should not update lock files. If the lock file is missing, or needs to be updated, an error is produced.

offline: bool

offline is set if we should never access the network, but otherwise continue operating if possible.

jobserver: Option<&'static Client>

A global static IPC control mechanism (used for managing parallel builds)

unstable_flags: CliUnstable

Cli flags of the form “-Z something” merged with config file values

unstable_flags_cli: Option<Vec<String>>

Cli flags of the form “-Z something”

easy: OnceLock<Mutex<Easy>>

A handle on curl easy mode for http calls

crates_io_source_id: OnceLock<SourceId>

Cache of the SourceId for crates.io

cache_rustc_info: bool

If false, don’t cache rustc --version --verbose invocations

invocation_instant: Instant

Monotonic start of this cargo invocation for reporting time elapsed.

invocation_time: Timestamp

Wall-clock time of this cargo invocation.

Currently used as the reference time for min-publish-age and -Zbuild-analysis.

target_dir: Option<Filesystem>

Target Directory via resolved Cli parameter

env: Env

Environment variable snapshot.

updated_sources: Mutex<HashSet<SourceId>>

Tracks which sources have been updated to avoid multiple updates.

credential_cache: Mutex<HashMap<CanonicalUrl, CredentialCacheValue>>

Cache of credentials from configuration or credential providers. Maps from url to credential value.

registry_config: Mutex<HashMap<SourceId, Option<RegistryConfig>>>

Cache of registry config from the [registries] table.

package_cache_lock: CacheLocker

Locks on the package and index caches.

http_config: OnceLock<CargoHttpConfig>

Cached configuration parsed by Cargo

http_async: OnceLock<Client>

future_incompat_config: OnceLock<CargoFutureIncompatConfig>

net_config: OnceLock<CargoNetConfig>

build_config: OnceLock<CargoBuildConfig>

target_cfgs: OnceLock<Vec<(String, TargetCfgConfig)>>

doc_extern_map: OnceLock<RustdocExternMap>

progress_config: ProgressConfig

env_config: OnceLock<Arc<HashMap<String, OsString>>>

nightly_features_allowed: bool

This should be false if:

• this is an artifact of the rustc distribution process for “stable” or for “beta”
• this is an #[test] that does not opt in with enable_nightly_features
• this is an integration test that uses ProcessBuilder that does not opt in with masquerade_as_nightly_cargo This should be true if:
• this is an artifact of the rustc distribution process for “nightly”
• this is being used in the rustc distribution process internally
• this is a cargo executable that was built from source
• this is an #[test] that called enable_nightly_features
• this is an integration test that uses ProcessBuilder that called masquerade_as_nightly_cargo It’s public to allow tests use nightly features. NOTE: this should be set before configure(). If calling this from an integration test, consider using ConfigBuilder::enable_nightly_features instead.

ws_roots: Mutex<HashMap<PathBuf, WorkspaceRootConfig>>

WorkspaceRootConfigs that have been found

global_cache_tracker: OnceLock<Mutex<GlobalCacheTracker>>

The global cache tracker is a database used to track disk cache usage.

deferred_global_last_use: OnceLock<Mutex<DeferredGlobalLastUse>>

A cache of modifications to make to GlobalContext::global_cache_tracker, saved to disk in a batch to improve performance.

Implementations

impl GlobalContext

pub fn new(shell: Shell, cwd: PathBuf, homedir: PathBuf) -> GlobalContext

Creates a new config instance.

This is typically used for tests or other special cases. default is preferred otherwise.

This does only minimal initialization. In particular, it does not load any config files from disk. Those will be loaded lazily as-needed.

pub fn default() -> CargoResult<GlobalContext>

Creates a new instance, with all default settings.

This does only minimal initialization. In particular, it does not load any config files from disk. Those will be loaded lazily as-needed.

pub fn home(&self) -> &Filesystem

Gets the user’s Cargo home directory (OS-dependent).

pub fn diagnostic_home_config(&self) -> String

Returns a path to display to the user with the location of their home config file (to only be used for displaying a diagnostics suggestion, such as recommending where to add a config value).

pub fn git_path(&self) -> Filesystem

Gets the Cargo Git directory (<cargo_home>/git).

pub fn git_checkouts_path(&self) -> Filesystem

Gets the directory of code sources Cargo checkouts from Git bare repos (<cargo_home>/git/checkouts).

pub fn git_db_path(&self) -> Filesystem

Gets the directory for all Git bare repos Cargo clones (<cargo_home>/git/db).

pub fn registry_base_path(&self) -> Filesystem

Gets the Cargo base directory for all registry information (<cargo_home>/registry).

pub fn registry_index_path(&self) -> Filesystem

Gets the Cargo registry index directory (<cargo_home>/registry/index).

pub fn registry_cache_path(&self) -> Filesystem

Gets the Cargo registry cache directory (<cargo_home>/registry/cache).

pub fn registry_source_path(&self) -> Filesystem

Gets the Cargo registry source directory (<cargo_home>/registry/src).

pub fn default_registry(&self) -> CargoResult<Option<String>>

Gets the default Cargo registry.

pub fn shell(&self) -> MutexGuard<'_, Shell>

Gets a reference to the shell, e.g., for writing error messages.

pub fn debug_assert_shell_not_borrowed(&self)

Assert Self::shell is not in use

Testing might not identify bugs with two accesses to shell at once due to conditional logic, so place this outside of the conditions to catch these bugs in more situations.

pub fn rustdoc(&self) -> CargoResult<&Path>

Gets the path to the rustdoc executable.

pub fn load_global_rustc( &self, ws: Option<&Workspace<'_>>, ) -> CargoResult<Rustc>

Gets the path to the rustc executable.

pub fn cargo_exe(&self) -> CargoResult<&Path>

Gets the path to the cargo executable.

pub fn updated_sources(&self) -> MutexGuard<'_, HashSet<SourceId>>

Which package sources have been updated, used to ensure it is only done once.

pub fn credential_cache( &self, ) -> MutexGuard<'_, HashMap<CanonicalUrl, CredentialCacheValue>>

Cached credentials from credential providers or configuration.

pub fn registry_config( &self, sid: &SourceId, ) -> CargoResult<Option<RegistryConfig>>

Gets the configuration for a remote registry.

The registry name is resolved from its index URL. This may emit a note if the resolved name differs from the source’s configured name. Returns None if no configuration is found.

Note: this does not load tokens from credentials.toml, see instead Self::registry_credentials.

pub fn registry_credentials( &self, sid: &SourceId, ) -> CargoResult<Option<RegistryCredential>>

Gets the credentials configured for a remote registry.

This loads credentials if needed and resolves the registry name in the same way as GlobalContext::registry_config.

pub fn config(&self) -> CargoResult<&ConfigStore>

Gets all config values from disk.

This will lazy-load the values as necessary. Callers are responsible for checking environment variables. Callers outside of the config module should avoid using this.

pub fn config_mut(&mut self) -> CargoResult<&mut ConfigStore>

Gets a mutable copy of the on-disk config values.

This requires the config values to already have been loaded. This currently only exists for cargo vendor to remove the source entries. This doesn’t respect environment variables. You should avoid using this if possible.

pub fn set_search_stop_path<P: Into<PathBuf>>(&mut self, path: P)

Sets the path where ancestor config file searching will stop. The given path is included, but its ancestors are not.

pub fn reload_cwd(&mut self) -> CargoResult<()>

Switches the working directory to std::env::current_dir

There is not a need to also call Self::reload_rooted_at.

pub fn reload_rooted_at<P: AsRef<Path>>(&mut self, path: P) -> CargoResult<()>

Reloads on-disk configuration values, starting at the given path and walking up its ancestors.

pub fn cwd(&self) -> &Path

The current working directory.

pub fn target_dir(&self) -> CargoResult<Option<Filesystem>>

The target output directory to use.

Returns None if the user has not chosen an explicit directory.

Callers should prefer Workspace::target_dir instead.

pub fn build_dir( &self, workspace_manifest_path: &Path, ) -> CargoResult<Option<Filesystem>>

The directory to use for intermediate build artifacts.

Callers should prefer Workspace::build_dir instead.

pub fn custom_build_dir( &self, val: &ConfigRelativePath, workspace_manifest_path: &Path, ) -> CargoResult<Filesystem>

The directory to use for intermediate build artifacts.

Callers should prefer Workspace::build_dir instead.

fn config_reader(&self) -> CargoResult<ConfigReader<'_>>

pub(crate) fn get_cv_with_env(&self, key: &ConfigKey) -> CargoResult<Option<CV>>

pub fn set_env(&mut self, env: HashMap<String, String>)

Helper primarily for testing.

pub(crate) fn env(&self) -> impl Iterator<Item = (&str, &str)>

Returns all environment variables as an iterator, keeping only entries where both the key and value are valid UTF-8.

pub fn get_env(&self, key: impl AsRef<OsStr>) -> CargoResult<&str>

Get the value of environment variable key through the snapshot in GlobalContext.

This can be used similarly to std::env::var.

pub fn get_env_os(&self, key: impl AsRef<OsStr>) -> Option<&OsStr>

Get the value of environment variable key through the snapshot in GlobalContext.

This can be used similarly to std::env::var_os.

pub fn get_string( &self, key: impl IntoIterator<Item = impl AsRef<str>>, ) -> CargoResult<OptValue<String>>

Get a string config value.

See get for more details.

fn string_to_path(&self, value: &str, definition: &Definition) -> PathBuf

pub fn configure( &mut self, verbose: u32, quiet: bool, color: Option<&str>, frozen: bool, locked: bool, offline: bool, target_dir: &Option<PathBuf>, unstable_flags: &[String], cli_config: &[String], ) -> CargoResult<()>

Update the instance based on settings typically passed in on the command-line.

This may also load the config from disk if it hasn’t already been loaded.

fn load_unstable_flags_from_config(&mut self) -> CargoResult<()>

pub fn cli_unstable(&self) -> &CliUnstable

pub fn extra_verbose(&self) -> bool

pub fn network_allowed(&self) -> bool

pub fn offline_flag(&self) -> Option<&'static str>

pub fn set_locked(&mut self, locked: bool)

pub fn lock_update_allowed(&self) -> bool

pub fn locked_flag(&self) -> Option<&'static str>

pub fn load_config(&self) -> CargoResult<ConfigStore>

Loads configuration from the filesystem.

pub(crate) fn load_config_unmerged(&self) -> CargoResult<Vec<ConfigStore>>

Like load_config but without merging config values.

This is primarily crafted for cargo config command.

fn load_unmerged_include( &self, config: &mut ConfigStore, seen: &mut HashSet<PathBuf>, output: &mut Vec<ConfigStore>, ) -> CargoResult<()>

Like load_includes but without merging config values.

This is primarily crafted for cargo config command.

fn load_config_from(&self, path: &Path) -> CargoResult<ConfigStore>

Start a config file discovery from a path and merges all config values found.

fn load_file(&self, path: &Path) -> CargoResult<ConfigStore>

Loads configuration from a path.

This is used during config file discovery.

fn _load_file( &self, path: &Path, seen: &mut HashSet<PathBuf>, includes: bool, definition_kind: DefinitionKind, ) -> CargoResult<ConfigStore>

Loads configuration from a path with options.

This is the implementation of loading configuration from a path.

• includes determines whether to load configs from ConfigInclude.
• seen is used to check for cyclic includes.
• definition_kind tells why a config is being loaded.

fn load_includes( &self, config: ConfigStore, seen: &mut HashSet<PathBuf>, definition_kind: DefinitionKind, ) -> CargoResult<ConfigStore>

Load any include files listed in the given config.

Returns config with the given include files merged into it.

• seen is used to check for cyclic includes.
• definition_kind tells why a config is being loaded.

fn include_paths( &self, config: &mut ConfigStore, remove: bool, ) -> CargoResult<Vec<ConfigInclude>>

Converts the include config value to a list of absolute paths.

pub(crate) fn cli_args_to_config(&self) -> CargoResult<ConfigStore>

Parses the CLI config args and returns them as a table.

fn merge_cli_args(&mut self) -> CargoResult<()>

Add config arguments passed on the command line.

fn get_file_path( &self, dir: &Path, filename_without_extension: &str, warn: bool, ) -> CargoResult<Option<PathBuf>>

The purpose of this function is to aid in the transition to using .toml extensions on Cargo’s config files, which were historically not used. Both ‘config.toml’ and ‘credentials.toml’ should be valid with or without extension. When both exist, we want to prefer the one without an extension for backwards compatibility, but warn the user appropriately.

fn walk_tree<F>(&self, pwd: &Path, home: &Path, walk: F) -> CargoResult<()>

where F: FnMut(&Path) -> CargoResult<()>,

pub fn get_registry_index(&self, registry: &str) -> CargoResult<Url>

Gets the index for a registry.

pub fn check_registry_index_not_set(&self) -> CargoResult<()>

Returns an error if registry.index is set.

fn resolve_registry_index(&self, index: &Value<String>) -> CargoResult<Url>

fn credentials_config(&self) -> CargoResult<&ConfigStore>

Gets configuration values from the credentials file, loading them on first use.

fn load_credentials(&self) -> CargoResult<ConfigStore>

Loads credentials config from the credentials file, if present.

fn maybe_get_tool( &self, tool: &str, from_config: &Option<ConfigRelativePath>, ) -> Option<PathBuf>

Looks for a path for tool in an environment variable or the given config, and returns None if it’s not present.

fn get_tool( &self, tool: Tool, from_config: &Option<ConfigRelativePath>, ) -> PathBuf

Returns the path for the given tool.

This will look for the tool in the following order:

1. From an environment variable matching the tool name (such as RUSTC).
2. From the given config value (which is usually something like build.rustc).
3. Finds the tool in the PATH environment variable.

This is intended for tools that are rustup proxies. If you need to get a tool that is not a rustup proxy, use maybe_get_tool instead.

pub fn paths_overrides( &self, ) -> CargoResult<OptValue<Vec<(String, Definition)>>>

Get the paths overrides config value.

pub fn jobserver_from_env(&self) -> Option<&Client>

pub fn http(&self) -> CargoResult<&Mutex<Easy>>

pub fn http_async(&self) -> CargoResult<&Client>

pub fn http_config(&self) -> CargoResult<&CargoHttpConfig>

pub fn future_incompat_config(&self) -> CargoResult<&CargoFutureIncompatConfig>

pub fn net_config(&self) -> CargoResult<&CargoNetConfig>

pub fn build_config(&self) -> CargoResult<&CargoBuildConfig>

pub fn progress_config(&self) -> &ProgressConfig

pub fn env_config(&self) -> CargoResult<&Arc<HashMap<String, OsString>>>

Get the env vars from the config [env] table which are force = true or don’t exist in the env snapshot GlobalContext::get_env.

pub fn validate_term_config(&self) -> CargoResult<()>

This is used to validate the term table has valid syntax.

This is necessary because loading the term settings happens very early, and in some situations (like cargo version) we don’t want to fail if there are problems with the config file.

pub fn target_cfgs(&self) -> CargoResult<&Vec<(String, TargetCfgConfig)>>

Returns a list of target.'cfg()' tables.

The list is sorted by the table name.

pub fn doc_extern_map(&self) -> CargoResult<&RustdocExternMap>

pub fn target_applies_to_host(&self) -> CargoResult<bool>

Returns true if the [target] table should be applied to host targets.

pub fn host_cfg_tuple(&self, target: &str) -> CargoResult<TargetConfig>

Returns the [host] table definition for the given target tuple.

pub fn target_cfg_tuple(&self, target: &str) -> CargoResult<TargetConfig>

Returns the [target] table definition for the given target tuple.

pub fn crates_io_source_id(&self) -> CargoResult<SourceId>

Returns the cached SourceId corresponding to the main repository.

This is the main cargo registry by default, but it can be overridden in a .cargo/config.toml.

pub fn invocation_instant(&self) -> Instant

pub fn invocation_time(&self) -> Timestamp

Returns the wall-clock time of this cargo invocation.

See the invocation_time field doc for details.

pub fn get<'de, T: Deserialize<'de>>( &self, key: impl IntoIterator<Item = impl AsRef<str>>, ) -> CargoResult<T>

Retrieves a config variable.

This supports most serde Deserialize types. Examples:

let v: Option<u32> = config.get(["some", "nested", "key"])?;
let v: Option<MyStruct> = config.get(["some", "key"])?;
let v: Option<HashMap<String, MyStruct>> = config.get(["foo"])?;

The key may be a dotted key, but this does NOT support TOML key quoting. Avoid key components that may have dots. For example, foo.'a.b'.bar" does not work if you try to fetch foo.‘a.b’“. You can fetch foo if it is a map, though.

pub fn assert_package_cache_locked<'a>( &self, mode: CacheLockMode, f: &'a Filesystem, ) -> &'a Path

Obtain a Path from a Filesystem, verifying that the appropriate lock is already currently held.

Locks are usually acquired via GlobalContext::acquire_package_cache_lock or GlobalContext::try_acquire_package_cache_lock.

pub fn acquire_package_cache_lock( &self, mode: CacheLockMode, ) -> CargoResult<CacheLock<'_>>

Acquires a lock on the global “package cache”, blocking if another cargo holds the lock.

See crate::util::cache_lock for an in-depth discussion of locking and lock modes.

pub fn try_acquire_package_cache_lock( &self, mode: CacheLockMode, ) -> CargoResult<Option<CacheLock<'_>>>

Acquires a lock on the global “package cache”, returning None if another cargo holds the lock.

See crate::util::cache_lock for an in-depth discussion of locking and lock modes.

pub fn global_cache_tracker( &self, ) -> CargoResult<MutexGuard<'_, GlobalCacheTracker>>

Returns a reference to the shared GlobalCacheTracker.

The package cache lock must be held to call this function (and to use it in general).

pub fn deferred_global_last_use( &self, ) -> CargoResult<MutexGuard<'_, DeferredGlobalLastUse>>

Returns a reference to the shared DeferredGlobalLastUse.

pub fn warning_handling(&self) -> CargoResult<WarningHandling>

Get the global WarningHandling configuration.

pub fn ws_roots(&self) -> MutexGuard<'_, HashMap<PathBuf, WorkspaceRootConfig>>

pub fn version_req_match_mode(&self) -> VersionReqMatchMode

Mode for matching version requirements against versions already selected / locked.

Once stabilized, this always returns VersionReqMatchMode::Prerelease (or remove and inline).

Trait Implementations

impl Debug for GlobalContext

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

Layout

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 2728 bytes