From 75dbb865917af9fc5fa5b985d8f9585aa16aa3d4 Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Wed, 21 Feb 2024 15:01:31 -0500 Subject: [PATCH] doc: link to `GlobalContext` item --- src/bin/cargo/cli.rs | 3 ++- src/bin/cargo/commands/install.rs | 2 +- .../core/compiler/job_queue/job_state.rs | 9 ++++--- src/cargo/sources/config.rs | 2 +- src/cargo/util/cache_lock.rs | 4 +-- src/cargo/util/config/de.rs | 2 +- src/cargo/util/config/environment.rs | 25 +++++++++++-------- src/cargo/util/config/mod.rs | 20 ++++++++------- src/doc/contrib/src/implementation/console.md | 6 ++--- tests/testsuite/config.rs | 10 ++++---- 10 files changed, 46 insertions(+), 37 deletions(-) diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs index 3203f658c35..da9d56217a8 100644 --- a/src/bin/cargo/cli.rs +++ b/src/bin/cargo/cli.rs @@ -25,7 +25,8 @@ pub fn main(gctx: &mut GlobalContext) -> CliResult { // Update the process-level notion of cwd if let Some(new_cwd) = args.get_one::("directory") { - // This is a temporary hack. This cannot access `Config`, so this is a bit messy. + // This is a temporary hack. + // This cannot access `GlobalContext`, so this is a bit messy. // This does not properly parse `-Z` flags that appear after the subcommand. // The error message is not as helpful as the standard one. let nightly_features_allowed = matches!(&*features::channel(), "nightly" | "dev"); diff --git a/src/bin/cargo/commands/install.rs b/src/bin/cargo/commands/install.rs index 86146098067..e188d6a0d67 100644 --- a/src/bin/cargo/commands/install.rs +++ b/src/bin/cargo/commands/install.rs @@ -111,7 +111,7 @@ pub fn exec(gctx: &mut GlobalContext, args: &ArgMatches) -> CliResult { // In general, we try to avoid normalizing paths in Cargo, // but in these particular cases we need it to fix rust-lang/cargo#10283. // (Handle `SourceId::for_path` and `Workspace::new`, - // but not `Config::reload_rooted_at` which is always cwd) + // but not `GlobalContext::reload_rooted_at` which is always cwd) let path = path.map(|p| paths::normalize_path(&p)); let version = args.get_one::("version"); diff --git a/src/cargo/core/compiler/job_queue/job_state.rs b/src/cargo/core/compiler/job_queue/job_state.rs index fe3a79adb98..12c04258d3e 100644 --- a/src/cargo/core/compiler/job_queue/job_state.rs +++ b/src/cargo/core/compiler/job_queue/job_state.rs @@ -28,11 +28,14 @@ pub struct JobState<'a, 'gctx> { /// output messages are processed on the same thread as they are sent from. `output` /// defines where to output in this case. /// - /// Currently the `Shell` inside `Config` is wrapped in a `RefCell` and thus can't be passed - /// between threads. This means that it isn't possible for multiple output messages to be - /// interleaved. In the future, it may be wrapped in a `Mutex` instead. In this case + /// Currently the [`Shell`] inside [`GlobalContext`] is wrapped in a `RefCell` and thus can't + /// be passed between threads. This means that it isn't possible for multiple output messages + /// to be interleaved. In the future, it may be wrapped in a `Mutex` instead. In this case /// interleaving is still prevented as the lock would be held for the whole printing of an /// output message. + /// + /// [`Shell`]: crate::core::Shell + /// [`GlobalContext`]: crate::GlobalContext output: Option<&'a DiagDedupe<'gctx>>, /// The job id that this state is associated with, used when sending diff --git a/src/cargo/sources/config.rs b/src/cargo/sources/config.rs index 49f63185ab7..7f9e9696327 100644 --- a/src/cargo/sources/config.rs +++ b/src/cargo/sources/config.rs @@ -120,7 +120,7 @@ impl<'gctx> SourceConfigMap<'gctx> { Ok(base) } - /// Returns the `Config` this source config map is associated with. + /// Returns the [`GlobalContext`] this source config map is associated with. pub fn gctx(&self) -> &'gctx GlobalContext { self.gctx } diff --git a/src/cargo/util/cache_lock.rs b/src/cargo/util/cache_lock.rs index fb879ebcda3..6e0249cc9e6 100644 --- a/src/cargo/util/cache_lock.rs +++ b/src/cargo/util/cache_lock.rs @@ -8,7 +8,7 @@ //! //! There is a global [`CacheLocker`] held inside cargo's venerable //! [`GlobalContext`]. The `CacheLocker` manages creating and tracking the locks -//! being held. There are methods on `Config` for managing the locks: +//! being held. There are methods on [`GlobalContext`] for managing the locks: //! //! - [`GlobalContext::acquire_package_cache_lock`] --- Acquires a lock. May block if //! another process holds a lock. @@ -468,7 +468,7 @@ pub struct CacheLocker { /// The state of the locker. /// /// [`CacheLocker`] uses interior mutability because it is stuffed inside - /// the global `Config`, which does not allow mutation. + /// [`GlobalContext`], which does not allow mutation. state: RefCell, } diff --git a/src/cargo/util/config/de.rs b/src/cargo/util/config/de.rs index 7ea2d431237..bfefad91ca2 100644 --- a/src/cargo/util/config/de.rs +++ b/src/cargo/util/config/de.rs @@ -8,7 +8,7 @@ use std::collections::HashSet; use std::vec; /// Serde deserializer used to convert config values to a target type using -/// `Config::get`. +/// [`GlobalContext::get`]. #[derive(Clone)] pub(super) struct Deserializer<'gctx> { pub(super) gctx: &'gctx GlobalContext, diff --git a/src/cargo/util/config/environment.rs b/src/cargo/util/config/environment.rs index dcf7cbcbf05..da9cd5e641c 100644 --- a/src/cargo/util/config/environment.rs +++ b/src/cargo/util/config/environment.rs @@ -28,18 +28,20 @@ fn make_case_insensitive_and_normalized_env( (case_insensitive_env, normalized_env) } -/// A snapshot of the environment variables available to [`super::GlobalContext`]. +/// A snapshot of the environment variables available to [`GlobalContext`]. /// -/// Currently, the [`Context`](super::GlobalContext) supports lookup of environment variables +/// Currently, the [`GlobalContext`] supports lookup of environment variables /// through two different means: /// -/// - [`Context::get_env`](super::GlobalContext::get_env) -/// and [`Context::get_env_os`](super::GlobalContext::get_env_os) +/// - [`GlobalContext::get_env`](super::GlobalContext::get_env) +/// and [`GlobalContext::get_env_os`](super::GlobalContext::get_env_os) /// for process environment variables (similar to [`std::env::var`] and [`std::env::var_os`]), -/// - Typed Config Value API via [`Context::get`](super::GlobalContext::get). +/// - Typed Config Value API via [`GlobalContext::get`](super::GlobalContext::get). /// This is only available for `CARGO_` prefixed environment keys. /// /// This type contains the env var snapshot and helper methods for both APIs. +/// +/// [`GlobalContext`]: super::GlobalContext #[derive(Debug)] pub struct Env { /// A snapshot of the process's environment variables. @@ -68,8 +70,8 @@ impl Env { pub fn new() -> Self { // ALLOWED: This is the only permissible usage of `std::env::vars{_os}` // within cargo. If you do need access to individual variables without - // interacting with `Config` system, please use `std::env::var{_os}` - // and justify the validity of the usage. + // interacting with the config system in [`GlobalContext`], please use + // `std::env::var{_os}` and justify the validity of the usage. #[allow(clippy::disallowed_methods)] let env: HashMap<_, _> = std::env::vars_os().collect(); let (case_insensitive_env, normalized_env) = make_case_insensitive_and_normalized_env(&env); @@ -105,9 +107,10 @@ impl Env { self.env.keys().filter_map(|k| k.to_str()) } - /// Get the value of environment variable `key` through the `Config` snapshot. + /// Get the value of environment variable `key` through the snapshot in + /// [`GlobalContext`](super::GlobalContext). /// - /// This can be used similarly to `std::env::var_os`. + /// This can be used similarly to [`std::env::var_os`]. /// On Windows, we check for case mismatch since environment keys are case-insensitive. pub fn get_env_os(&self, key: impl AsRef) -> Option { match self.env.get(key.as_ref()) { @@ -152,7 +155,7 @@ impl Env { /// Get the value of environment variable `key` as a `&str`. /// Returns `None` if `key` is not in `self.env` or if the value is not valid UTF-8. /// - /// This is intended for use in private methods of `Config`, + /// This is intended for use in private methods of [`GlobalContext`](super::GlobalContext), /// and does not check for env key case mismatch. /// /// This is case-sensitive on Windows (even though environment keys on Windows are usually @@ -172,7 +175,7 @@ impl Env { /// Check if the environment contains `key`. /// - /// This is intended for use in private methods of `Config`, + /// This is intended for use in private methods of [`GlobalContext`](super::GlobalContext), /// and does not check for env key case mismatch. /// See the docstring of [`Env::get_str`] for more context. pub(super) fn contains_key(&self, key: impl AsRef) -> bool { diff --git a/src/cargo/util/config/mod.rs b/src/cargo/util/config/mod.rs index 30536b1adf9..c64458990f4 100644 --- a/src/cargo/util/config/mod.rs +++ b/src/cargo/util/config/mod.rs @@ -1,12 +1,12 @@ //! Cargo's config system. //! -//! The `Config` object contains general information about the environment, +//! 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 -//! `Config::get` method. It uses `serde` to translate config values to a +//! [`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: @@ -329,7 +329,7 @@ impl GlobalContext { } } - /// Creates a new Config instance, with all default settings. + /// 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. @@ -811,16 +811,18 @@ impl GlobalContext { } } - /// Get the value of environment variable `key` through the `Config` snapshot. + /// Get the value of environment variable `key` through the snapshot in + /// [`GlobalContext`]. /// - /// This can be used similarly to `std::env::var`. + /// This can be used similarly to [`std::env::var`]. pub fn get_env(&self, key: impl AsRef) -> CargoResult { self.env.get_env(key) } - /// Get the value of environment variable `key` through the `Config` snapshot. + /// Get the value of environment variable `key` through the snapshot in + /// [`GlobalContext`]. /// - /// This can be used similarly to `std::env::var_os`. + /// This can be used similarly to [`std::env::var_os`]. pub fn get_env_os(&self, key: impl AsRef) -> Option { self.env.get_env_os(key) } @@ -1001,7 +1003,7 @@ impl GlobalContext { .map_err(|e| anyhow!("invalid configuration for key `{}`\n{}", key, e)) } - /// Update the Config instance based on settings typically passed in on + /// 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 @@ -1646,7 +1648,7 @@ impl GlobalContext { /// /// 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`. + /// without requiring `mut` access to the [`GlobalContext`]. /// /// If the credentials are already loaded, this function does nothing. pub fn load_credentials(&self) -> CargoResult<()> { diff --git a/src/doc/contrib/src/implementation/console.md b/src/doc/contrib/src/implementation/console.md index 99d31b951ae..4874a931939 100644 --- a/src/doc/contrib/src/implementation/console.md +++ b/src/doc/contrib/src/implementation/console.md @@ -1,8 +1,8 @@ # Console Output All of Cargo's output should go through the [`Shell`] struct. You can normally -obtain the `Shell` instance from the [`Config`] struct. Do **not** use the std -`println!` macros. +obtain the `Shell` instance from the [`GlobalContext`] struct. Do **not** use +the std `println!` macros. Most of Cargo's output goes to stderr. When running in JSON mode, the output goes to stdout. @@ -17,7 +17,7 @@ if they are unable to be displayed. This is generally automatically handled in the [`JobQueue`] as it processes each message. [`Shell`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/shell.rs -[`Config`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/config/mod.rs +[`GlobalContext`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/config/mod.rs [`drop_print`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1820-L1848 [`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue/mod.rs diff --git a/tests/testsuite/config.rs b/tests/testsuite/config.rs index e2d8d662c63..802d7e4423d 100644 --- a/tests/testsuite/config.rs +++ b/tests/testsuite/config.rs @@ -80,9 +80,9 @@ impl GlobalContextBuilder { /// Sets the test root directory. /// /// This generally should not be necessary. It is only useful if you want - /// to create a `Config` from within a thread. Since Cargo's testsuite - /// uses thread-local storage, this can be used to avoid accessing that - /// thread-local storage. + /// to create a [`GlobalContext`] from within a thread. Since Cargo's + /// testsuite uses thread-local storage, this can be used to avoid accessing + /// that thread-local storage. /// /// Default is [`paths::root`]. pub fn root(&mut self, path: impl Into) -> &mut Self { @@ -90,12 +90,12 @@ impl GlobalContextBuilder { self } - /// Creates the `Config`. + /// Creates the [`GlobalContext`]. pub fn build(&self) -> GlobalContext { self.build_err().unwrap() } - /// Creates the `Config`, returning a Result. + /// Creates the [`GlobalContext`], returning a Result. pub fn build_err(&self) -> CargoResult { let root = self.root.clone().unwrap_or_else(|| paths::root()); let output = Box::new(fs::File::create(root.join("shell.out")).unwrap());