Skip to content

docs(contrib): Move overview to lib #11809

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Merged
merged 3 commits into from
Mar 9, 2023
Merged

docs(contrib): Move overview to lib #11809

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7b27ff3
docs(contrib): Eagerly link to zulip
epage Mar 6, 2023
2b0b3b2
docs(lib): Be more succinct in intro
epage Jan 31, 2023
0f9bfb9
docs(contrib): Move overview to lib
epage Jan 31, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions src/cargo/core/compiler/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,14 +33,14 @@

pub mod artifact;
mod build_config;
mod build_context;
pub(crate) mod build_context;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not really a big deal. Just a bit worried making these modules public. Maintainer now need to gatekeep any misuse during the review.

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;
Expand Down
121 changes: 80 additions & 41 deletions src/cargo/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,53 +9,92 @@

//! # Cargo as a library
//!
//! Cargo, the Rust package manager, is also provided as a library.
//!
//! There are two places you can find API documentation of cargo-the-library,
//!
//! - <https://docs.rs/cargo> and
//! - <https://doc.rust-lang.org/nightly/nightly-rustc/cargo>.
//!
//! Each of them targets on a slightly different audience.
//!
//! ## For external tool developers
//!
//! The documentation on <https://docs.rs/cargo> contains public-facing items in cargo-the-library.
//! External tool developers may find it useful when trying to reuse existing building blocks from Cargo.
//! However, using Cargo as a library has drawbacks, especially cargo-the-library is unstable,
//! 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.
//!
//! Cargo API documentation on docs.rs gets updates along with each Rust release.
//! Its version always has a 0 major version to state it is unstable.
//! The minor version is always +1 of rustc's minor version
//! (that is, `cargo 0.66.0` corresponds to `rustc 1.65`).
//!
//! ## For Cargo contributors
//! - <https://docs.rs/cargo>: targeted at external tool developers using cargo-the-library
//! - Released with every rustc release
//! - <https://doc.rust-lang.org/nightly/nightly-rustc/cargo>: targeted at cargo contributors
//! - Updated on each update of the `cargo` submodule in `rust-lang/rust`
//!
//! The documentation on <https://doc.rust-lang.org/nightly/nightly-rustc/cargo> contains all items in Cargo.
//! Contributors of Cargo may find it useful as a reference of Cargo's implementation details.
//! It's built with `--document-private-items` rustdoc flag,
//! so you might expect to see some noise and strange items here.
//! The Cargo team and contributors strive for jotting down every details
//! from their brains in each issue and PR.
//! However, something might just disappear in the air with no reason.
//! This documentation can be seen as their extended minds,
//! sharing designs and hacks behind both public and private interfaces.
//! **WARNING:** Using Cargo as a library has drawbacks, particulary the API is unstable,
//! 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.
//!
//! 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
//! ## Overview
//!
//! - [`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).
//! - [`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.
//!
//! 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)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The layout looks fine here, though I prefer reference-style links. They are more readable at source code level.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I try them every once in a while but always feel like they are more of a pain to initially write (duplicating the referencing, jumping back and forth) and then dealing with later (more places to touch when updating).

//! 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
//!
Expand Down
4 changes: 2 additions & 2 deletions src/cargo/ops/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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;
Expand Down
107 changes: 1 addition & 106 deletions src/doc/contrib/src/architecture/codebase.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
2 changes: 1 addition & 1 deletion src/doc/contrib/src/architecture/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,4 @@ intended to give you links into the code which is hopefully commented with
more in-depth information.

If you feel something is missing that would help you, feel free to ask on
Zulip.
[Zulip](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo).