diff --git a/src/cargo/core/compiler/mod.rs b/src/cargo/core/compiler/mod.rs index eed0085cfb6..65239707824 100644 --- a/src/cargo/core/compiler/mod.rs +++ b/src/cargo/core/compiler/mod.rs @@ -33,14 +33,14 @@ pub mod artifact; mod build_config; -mod build_context; +pub(crate) mod build_context; mod build_plan; mod compilation; mod compile_kind; -mod context; +pub(crate) mod context; mod crate_type; mod custom_build; -mod fingerprint; +pub(crate) mod fingerprint; pub mod future_incompat; mod job_queue; mod layout; diff --git a/src/cargo/lib.rs b/src/cargo/lib.rs index 80f620cd0db..cd60880bf1f 100644 --- a/src/cargo/lib.rs +++ b/src/cargo/lib.rs @@ -20,21 +20,81 @@ //! and there is no clear path to stabilize it soon at the time of writing. See [The Cargo Book: //! External tools] for more on this topic. //! -//! ## For Cargo contributors +//! ## Overview //! -//! If you are just diving into Cargo internals, [Cargo Architecture Overview] -//! is the best material to get a broader context of how Cargo works under the hood. -//! Things also worth a read are important concepts reside in source code, -//! which Cargo developers have been crafting for a while, namely +//! - [`ops`]: +//! Every major operation is implemented here. Each command is a thin wrapper around ops. +//! - [`ops::cargo_compile`]: +//! This is the entry point for all the compilation commands. This is a +//! good place to start if you want to follow how compilation starts and +//! flows to completion. +//! - [`core::resolver`]: +//! This is the dependency and feature resolvers. +//! - [`core::compiler`]: +//! This is the code responsible for running `rustc` and `rustdoc`. +//! - [`core::compiler::build_context`]: +//! The [`BuildContext`]['core::compiler::BuildContext] is the result of the "front end" of the +//! build process. This contains the graph of work to perform and any settings necessary for +//! `rustc`. After this is built, the next stage of building is handled in +//! [`Context`][core::compiler::Context]. +//! - [`core::compiler::context`]: +//! The `Context` is the mutable state used during the build process. This +//! is the core of the build process, and everything is coordinated through +//! this. +//! - [`core::compiler::fingerprint`]: +//! The `fingerprint` module contains all the code that handles detecting +//! if a crate needs to be recompiled. +//! - [`core::source`]: +//! The [`core::Source`] trait is an abstraction over different sources of packages. +//! Sources are uniquely identified by a [`core::SourceId`]. Sources are implemented in the [`sources`] +//! directory. +//! - [`util`]: +//! This directory contains generally-useful utility modules. +//! - [`util::config`]: +//! This directory contains the config parser. It makes heavy use of +//! [serde](https://serde.rs/) to merge and translate config values. The +//! [`util::Config`] is usually accessed from the +//! [`core::Workspace`] +//! though references to it are scattered around for more convenient access. +//! - [`util::toml`]: +//! This directory contains the code for parsing `Cargo.toml` files. +//! - [`ops::lockfile`]: +//! This is where `Cargo.lock` files are loaded and saved. //! -//! - [`cargo::core::resolver`](crate::core::resolver), -//! - [`cargo::core::compiler::fingerprint`](core/compiler/fingerprint/index.html), -//! - [`cargo::util::config`](crate::util::config), -//! - [`cargo::ops::fix`](ops/fix/index.html), and -//! - [`cargo::sources::registry`](crate::sources::registry). -//! -//! This API documentation is published on each push of rust-lang/cargo master branch. -//! In other words, it always reflects the latest doc comments in source code on master branch. +//! Related crates: +//! - [`cargo-platform`](https://crates.io/crates/cargo-platform) +//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_platform)): +//! This library handles parsing `cfg` expressions. +//! - [`cargo-util`](https://crates.io/crates/cargo-util) +//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_util)): +//! This contains general utility code that is shared between cargo and the testsuite +//! - [`crates-io`](https://crates.io/crates/crates-io) +//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/crates_io)): +//! This contains code for accessing the crates.io API. +//! - [`home`](https://crates.io/crates/home): +//! This library is shared between cargo and rustup and is used for finding their home directories. +//! This is not directly depended upon with a `path` dependency; cargo uses the version from crates.io. +//! It is intended to be versioned and published independently of Rust's release system. +//! Whenever a change needs to be made, bump the version in Cargo.toml and `cargo publish` it manually, and then update cargo's `Cargo.toml` to depend on the new version. +//! - [`cargo-test-support`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-support) +//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_support/index.html)): +//! This contains a variety of code to support writing tests +//! - [`cargo-test-macro`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-macro) +//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_macro/index.html)): +//! This is the `#[cargo_test]` proc-macro used by the test suite to define tests. +//! - [`credential`](https://github.com/rust-lang/cargo/tree/master/crates/credential) +//! This subdirectory contains several packages for implementing the +//! experimental +//! [credential-process](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#credential-process) +//! feature. +//! - [`mdman`](https://github.com/rust-lang/cargo/tree/master/crates/mdman) +//! ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/mdman/index.html)): +//! This is a utility for generating cargo's man pages. See [Building the man +//! pages](https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages) +//! for more information. +//! - [`resolver-tests`](https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests) +//! This is a dedicated package that defines tests for the [dependency +//! resolver][core::resolver]. //! //! ## Contribute to Cargo documentations //! diff --git a/src/cargo/ops/mod.rs b/src/cargo/ops/mod.rs index d54ae244655..dd2c7520770 100644 --- a/src/cargo/ops/mod.rs +++ b/src/cargo/ops/mod.rs @@ -34,7 +34,7 @@ pub use self::vendor::{vendor, VendorOptions}; pub mod cargo_add; mod cargo_clean; -mod cargo_compile; +pub(crate) mod cargo_compile; pub mod cargo_config; mod cargo_doc; mod cargo_fetch; @@ -51,7 +51,7 @@ mod cargo_test; mod cargo_uninstall; mod common_for_install_and_uninstall; mod fix; -mod lockfile; +pub(crate) mod lockfile; pub(crate) mod registry; mod resolve; pub mod tree; diff --git a/src/doc/contrib/src/architecture/codebase.md b/src/doc/contrib/src/architecture/codebase.md index 45c6e0e2f1d..e33fc51c237 100644 --- a/src/doc/contrib/src/architecture/codebase.md +++ b/src/doc/contrib/src/architecture/codebase.md @@ -1,108 +1,3 @@ # Codebase Overview -This is a very high-level overview of the Cargo codebase. - -* [`src/bin/cargo`](https://github.com/rust-lang/cargo/tree/master/src/bin/cargo) - --- Cargo is split in a library and a binary. This is the binary side that - handles argument parsing, and then calls into the library to perform the - appropriate subcommand. Each Cargo subcommand is a separate module here. See - [SubCommands](subcommands.md). - -* [`src/cargo/ops`](https://github.com/rust-lang/cargo/tree/master/src/cargo/ops) - --- Every major operation is implemented here. This is where the binary CLI - usually calls into to perform the appropriate action. - - * [`src/cargo/ops/cargo_compile/mod.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile/mod.rs) - --- This is the entry point for all the compilation commands. This is a - good place to start if you want to follow how compilation starts and - flows to completion. - -* [`src/cargo/core/resolver`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/resolver) - --- This is the dependency and feature resolvers. - -* [`src/cargo/core/compiler`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/compiler) - --- This is the code responsible for running `rustc` and `rustdoc`. - - * [`src/cargo/core/compiler/build_context/mod.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/mod.rs) - --- The `BuildContext` is the result of the "front end" of the build - process. This contains the graph of work to perform and any settings - necessary for `rustc`. After this is built, the next stage of building - is handled in `Context`. - - * [`src/cargo/core/compiler/context`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/context/mod.rs) - --- The `Context` is the mutable state used during the build process. This - is the core of the build process, and everything is coordinated through - this. - - * [`src/cargo/core/compiler/fingerprint.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs) - --- The `fingerprint` module contains all the code that handles detecting - if a crate needs to be recompiled. - -* [`src/cargo/core/source`](https://github.com/rust-lang/cargo/tree/master/src/cargo/core/source) - --- The `Source` trait is an abstraction over different sources of packages. - Sources are uniquely identified by a `SourceId`. Sources are implemented in - the - [`src/cargo/sources`](https://github.com/rust-lang/cargo/tree/master/src/cargo/sources) - directory. - -* [`src/cargo/util`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util) - --- This directory contains generally-useful utility modules. - -* [`src/cargo/util/config`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util/config) - --- This directory contains the config parser. It makes heavy use of - [serde](https://serde.rs/) to merge and translate config values. The - `Config` is usually accessed from the - [`Workspace`](https://github.com/rust-lang/cargo/blob/master/src/cargo/core/workspace.rs), - though references to it are scattered around for more convenient access. - -* [`src/cargo/util/toml`](https://github.com/rust-lang/cargo/tree/master/src/cargo/util/toml) - --- This directory contains the code for parsing `Cargo.toml` files. - - * [`src/cargo/ops/lockfile.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/lockfile.rs) - --- This is where `Cargo.lock` files are loaded and saved. - -* [`src/doc`](https://github.com/rust-lang/cargo/tree/master/src/doc) - --- This directory contains Cargo's documentation and man pages. - -* [`src/etc`](https://github.com/rust-lang/cargo/tree/master/src/etc) - --- These are files that get distributed in the `etc` directory in the Rust release. - The man pages are auto-generated by a script in the `src/doc` directory. - -* [`crates`](https://github.com/rust-lang/cargo/tree/master/crates) - --- A collection of independent crates used by Cargo. - -## Extra crates - -Some functionality is split off into separate crates, usually in the -[`crates`](https://github.com/rust-lang/cargo/tree/master/crates) directory. - -* [`cargo-platform`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-platform) - --- This library handles parsing `cfg` expressions. -* [`cargo-test-macro`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-macro) - --- This is a proc-macro used by the test suite to define tests. More - information can be found at [`cargo_test` - attribute](../tests/writing.md#cargo_test-attribute). -* [`cargo-test-support`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-support) - --- This contains a variety of code to support [writing - tests](../tests/writing.md). -* [`cargo-util`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-util) - --- This contains general utility code that is shared between cargo and the - testsuite. -* [`crates-io`](https://github.com/rust-lang/cargo/tree/master/crates/crates-io) - --- This contains code for accessing the crates.io API. -* [`credential`](https://github.com/rust-lang/cargo/tree/master/crates/credential) - --- This subdirectory contains several packages for implementing the - experimental - [credential-process](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#credential-process) - feature. -* [`home`](https://github.com/rust-lang/cargo/tree/master/crates/home) --- This library is shared between cargo and rustup and is used for finding their home directories. - This is not directly depended upon with a `path` dependency; cargo uses the version from crates.io. - It is intended to be versioned and published independently of Rust's release system. - Whenever a change needs to be made, bump the version in Cargo.toml and `cargo publish` it manually, and then update cargo's `Cargo.toml` to depend on the new version. -* [`mdman`](https://github.com/rust-lang/cargo/tree/master/crates/mdman) - --- This is a utility for generating cargo's man pages. See [Building the man - pages](https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages) - for more information. -* [`resolver-tests`](https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests) - --- This is a dedicated package that defines tests for the [dependency - resolver](../architecture/packages.md#resolver). +See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html)