# Struct cargo::util::config::Config

source ·

    pub struct Config {Show 36 fields
        home_path: Filesystem,
        shell: RefCell<Shell>,
        values: LazyCell<HashMap<String, ConfigValue>>,
        credential_values: LazyCell<HashMap<String, ConfigValue>>,
        cli_config: Option<Vec<String>>,
        cwd: PathBuf,
        search_stop_path: Option<PathBuf>,
        cargo_exe: LazyCell<PathBuf>,
        rustdoc: LazyCell<PathBuf>,
        extra_verbose: bool,
        frozen: bool,
        locked: bool,
        offline: bool,
        jobserver: Option<Client>,
        unstable_flags: CliUnstable,
        unstable_flags_cli: Option<Vec<String>>,
        easy: LazyCell<RefCell<Easy>>,
        crates_io_source_id: LazyCell<SourceId>,
        cache_rustc_info: bool,
        creation_time: Instant,
        target_dir: Option<Filesystem>,
        env: Env,
        updated_sources: LazyCell<RefCell<HashSet<SourceId>>>,
        credential_cache: LazyCell<RefCell<HashMap<CanonicalUrl, CredentialCacheValue>>>,
        registry_config: LazyCell<RefCell<HashMap<SourceId, Option<RegistryConfig>>>>,
        package_cache_lock: RefCell<Option<(Option<FileLock>, usize)>>,
        http_config: LazyCell<CargoHttpConfig>,
        future_incompat_config: LazyCell<CargoFutureIncompatConfig>,
        net_config: LazyCell<CargoNetConfig>,
        build_config: LazyCell<CargoBuildConfig>,
        target_cfgs: LazyCell<Vec<(String, TargetCfgConfig)>>,
        doc_extern_map: LazyCell<RustdocExternMap>,
        progress_config: ProgressConfig,
        env_config: LazyCell<EnvConfig>,
        pub nightly_features_allowed: bool,
        pub ws_roots: RefCell<HashMap<PathBuf, WorkspaceRootConfig>>,
    }

Expand description

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: RefCell<Shell>`

Information about how to write messages to the shell

§`values: LazyCell<HashMap<String, ConfigValue>>`

A collection of configuration options

§`credential_values: LazyCell<HashMap<String, ConfigValue>>`

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: LazyCell<PathBuf>`

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

§`rustdoc: LazyCell<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<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: LazyCell<RefCell<Easy>>`

A handle on curl easy mode for http calls

§`crates_io_source_id: LazyCell<SourceId>`

Cache of the `SourceId` for crates.io

§`cache_rustc_info: bool`

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

§`creation_time: Instant`

Creation time of this config, used to output the total build time

§`target_dir: Option<Filesystem>`

Target Directory via resolved Cli parameter

§`env: Env`

Environment variable snapshot.

§`updated_sources: LazyCell<RefCell<HashSet<SourceId>>>`

Tracks which sources have been updated to avoid multiple updates.

§`credential_cache: LazyCell<RefCell<HashMap<CanonicalUrl, CredentialCacheValue>>>`

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

§`registry_config: LazyCell<RefCell<HashMap<SourceId, Option<RegistryConfig>>>>`

Cache of registry config from from the `[registries]` table.

§`package_cache_lock: RefCell<Option<(Option<FileLock>, usize)>>`

Lock, if held, of the global package cache along with the number of acquisitions so far.

§`http_config: LazyCell<CargoHttpConfig>`

Cached configuration parsed by Cargo

§`future_incompat_config: LazyCell<CargoFutureIncompatConfig>`§`net_config: LazyCell<CargoNetConfig>`§`build_config: LazyCell<CargoBuildConfig>`§`target_cfgs: LazyCell<Vec<(String, TargetCfgConfig)>>`§`doc_extern_map: LazyCell<RustdocExternMap>`§`progress_config: ProgressConfig`§`env_config: LazyCell<EnvConfig>`§`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: RefCell<HashMap<PathBuf, WorkspaceRootConfig>>`

WorkspaceRootConfigs that have been found

## Implementations§

source§

### impl Config

source

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

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.

source

#### pub fn default() -> CargoResult<Config>

Creates a new Config 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.

source

#### pub fn home(&self) -> &Filesystem

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

source

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

source

#### pub fn git_path(&self) -> Filesystem

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

source

#### pub fn registry_base_path(&self) -> Filesystem

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

source

#### pub fn registry_index_path(&self) -> Filesystem

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

source

#### pub fn registry_cache_path(&self) -> Filesystem

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

source

#### pub fn registry_source_path(&self) -> Filesystem

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

source

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

Gets the default Cargo registry.

source

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

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

source

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

Gets the path to the `rustdoc` executable.

source

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

Gets the path to the `rustc` executable.

source

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

Gets the path to the `cargo` executable.

source

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

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

source

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

Cached credentials from credential providers or configuration.

source

#### pub(crate) fn registry_config( &self ) -> RefMut<'_, HashMap<SourceId, Option<RegistryConfig>>>

Cache of already parsed registries from the `[registries]` table.

source

#### pub fn values(&self) -> CargoResult<&HashMap<String, ConfigValue>>

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.

source

#### pub fn values_mut(&mut self) -> CargoResult<&mut HashMap<String, ConfigValue>>

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.

source

#### pub fn set_values( &self, values: HashMap<String, ConfigValue> ) -> CargoResult<()>

source

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

source

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

source

#### pub fn cwd(&self) -> &Path

The current working directory.

source

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

source

#### fn get_cv(&self, key: &ConfigKey) -> CargoResult<Option<ConfigValue>>

Get a configuration value by key.

This does NOT look at environment variables. See `get_cv_with_env` for a variant that supports environment variables.

source

#### fn get_cv_helper( &self, key: &ConfigKey, vals: &HashMap<String, ConfigValue> ) -> CargoResult<Option<ConfigValue>>

source

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

This is a helper for getting a CV from a file or env var.

source

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

Helper primarily for testing.

source

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

source

#### fn env_keys(&self) -> impl Iterator<Item = &str>

Returns all environment variable keys, filtering out keys that are not valid UTF-8.

source

#### fn get_config_env<T>(&self, key: &ConfigKey) -> Result<OptValue<T>, ConfigError>where T: FromStr, <T as FromStr>::Err: Display,

source

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

Get the value of environment variable `key` through the `Config` snapshot.

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

source

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

Get the value of environment variable `key` through the `Config` snapshot.

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

source

#### fn has_key(&self, key: &ConfigKey, env_prefix_ok: bool) -> CargoResult<bool>

Check if the `Config` contains a given `ConfigKey`.

See `ConfigMapAccess` for a description of `env_prefix_ok`.

source

#### fn check_environment_key_case_mismatch(&self, key: &ConfigKey)

source

#### pub fn get_string(&self, key: &str) -> CargoResult<OptValue<String>>

Get a string config value.

See `get` for more details.

source

#### pub fn get_path(&self, key: &str) -> CargoResult<OptValue<PathBuf>>

Get a config value that is expected to be a path.

This returns a relative path if the value does not contain any directory separators. See `ConfigRelativePath::resolve_program` for more details.

source

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

source

#### pub fn get_list( &self, key: &str ) -> CargoResult<OptValue<Vec<(String, Definition)>>>

Get a list of strings.

DO NOT USE outside of the config module. `pub` will be removed in the future.

NOTE: this does not support environment variables. Use `get` instead if you want that.

source

#### fn _get_list( &self, key: &ConfigKey ) -> CargoResult<OptValue<Vec<(String, Definition)>>>

source

#### fn get_list_or_string( &self, key: &ConfigKey, merge: bool ) -> CargoResult<Vec<(String, Definition)>>

Helper for StringList type to get something that is a string or list.

source

#### fn get_env_list( &self, key: &ConfigKey, output: &mut Vec<(String, Definition)> ) -> CargoResult<()>

Internal method for getting an environment variable as a list.

source

#### fn get_table( &self, key: &ConfigKey ) -> CargoResult<OptValue<HashMap<String, CV>>>

Low-level method for getting a config value as an `OptValue<HashMap<String, CV>>`.

NOTE: This does not read from env. The caller is responsible for that.

source

#### fn get_integer(&self, key: &ConfigKey) -> Result<OptValue<i64>, ConfigError>

Low-level private method for getting a config value as an OptValue.

source

#### fn get_bool(&self, key: &ConfigKey) -> Result<OptValue<bool>, ConfigError>

Low-level private method for getting a config value as an OptValue.

source

#### fn get_string_priv( &self, key: &ConfigKey ) -> Result<OptValue<String>, ConfigError>

Low-level private method for getting a config value as an OptValue.

source

#### fn expected<T>(&self, ty: &str, key: &ConfigKey, val: &CV) -> CargoResult<T>

Generate an error when the given value is the wrong type.

source

#### 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 Config 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.

source

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

source

#### pub fn cli_unstable(&self) -> &CliUnstable

source

#### pub fn extra_verbose(&self) -> bool

source

#### pub fn network_allowed(&self) -> bool

source

#### pub fn offline(&self) -> bool

source

#### pub fn frozen(&self) -> bool

source

#### pub fn locked(&self) -> bool

source

#### pub fn lock_update_allowed(&self) -> bool

source

#### pub fn load_values(&self) -> CargoResult<HashMap<String, ConfigValue>>

Loads configuration from the filesystem.

source

#### pub(crate) fn load_values_unmerged(&self) -> CargoResult<Vec<ConfigValue>>

Like `load_values` but without merging config values.

This is primarily crafted for `cargo config` command.

source

#### fn load_unmerged_include( &self, cv: &mut CV, seen: &mut HashSet<PathBuf>, output: &mut Vec<CV> ) -> CargoResult<()>

Like `load_includes` but without merging config values.

This is primarily crafted for `cargo config` command.

source

#### fn load_values_from( &self, path: &Path ) -> CargoResult<HashMap<String, ConfigValue>>

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

source

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

Loads a config value from a path.

This is used during config file discovery.

source

#### fn _load_file( &self, path: &Path, seen: &mut HashSet<PathBuf>, includes: bool, why_load: WhyLoad ) -> CargoResult<ConfigValue>

Loads a config value from a path with options.

This is actual implementation of loading a config value from a path.

- `includes` determines whether to load configs from `config-include`.
- `seen` is used to check for cyclic includes.
- `why_load` tells why a config is being loaded.

source

#### fn load_includes( &self, value: CV, seen: &mut HashSet<PathBuf>, why_load: WhyLoad ) -> CargoResult<CV>

Load any `include` files listed in the given `value`.

Returns `value` with the given include files merged into it.

- `seen` is used to check for cyclic includes.
- `why_load` tells why a config is being loaded.

source

#### fn include_paths( &self, cv: &mut CV, remove: bool ) -> CargoResult<Vec<(String, PathBuf, Definition)>>

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

source

#### pub(crate) fn cli_args_as_table(&self) -> CargoResult<ConfigValue>

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

source

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

Add config arguments passed on the command line.

source

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

source

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

source

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

Gets the index for a registry.

source

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

Returns an error if `registry.index` is set.

source

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

source

#### pub fn load_credentials(&self) -> CargoResult<()>

Loads credentials config from the credentials file, if present.

The credentials are loaded into a separate field to enable them to be lazy-loaded after the main configuration has been loaded, without requiring `mut` access to the `Config`.

If the credentials are already loaded, this function does nothing.

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

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

source

#### pub fn progress_config(&self) -> &ProgressConfig

source

#### pub fn env_config(&self) -> CargoResult<&EnvConfig>

source

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

source

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

Returns a list of [target.‘cfg()’] tables.

The list is sorted by the table name.

source

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

source

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

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

source

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

Returns the `[host]` table definition for the given target triple.

source

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

Returns the `[target]` table definition for the given target triple.

source

#### 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`.

source

#### pub fn creation_time(&self) -> Instant

source

#### pub fn get<'de, T: Deserialize<'de>>(&self, key: &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.

source

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

source

#### pub fn acquire_package_cache_lock(&self) -> CargoResult<PackageCacheLock<'_>>

Acquires an exclusive lock on the global “package cache”

This lock is global per-process and can be acquired recursively. An RAII structure is returned to release the lock, and if this process abnormally terminates the lock is also released.

source

#### pub fn release_package_cache_lock(&self)

## Trait Implementations§

source§

### impl Debug for Config

source§

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

Formats the value using the given formatter. Read more

## Auto Trait Implementations§

§

### impl !RefUnwindSafe for Config

§

### impl !Send for Config

§

### impl !Sync for Config

§

### impl Unpin for Config

§

### impl !UnwindSafe for Config

## Blanket Implementations§

source§

### impl<T> Any for Twhere T: 'static + ?Sized,

source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
source§

### impl<T> Borrow<T> for Twhere T: ?Sized,

source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

### impl<T> From<T> for T

source§

#### fn from(t: T) -> T

Returns the argument unchanged.

source§

### impl<T> Instrument for T

source§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided `Span`, returning an `Instrumented` wrapper. Read more
source§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
source§

### impl<T, U> Into<U> for Twhere U: From<T>,

source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

source§

### impl<T> Same<T> for T

§

#### type Output = T

Should always be `Self`
source§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

### impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

§

#### fn vzip(self) -> V

source§

### impl<T> WithSubscriber for T

source§

#### fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>where S: Into<Dispatch>,

Attaches the provided `Subscriber` to this type, returning a `WithDispatch` wrapper. Read more
source§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a `WithDispatch` wrapper. Read more

## 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: 1968 bytes