From c2cd0fdeeb7c8ebca8c55240f576884648d90231 Mon Sep 17 00:00:00 2001 From: Hidehito Yabuuchi Date: Sat, 23 Feb 2019 18:32:34 +0900 Subject: [PATCH 1/3] Link from ARCHITECTURE.md to docs.rs and github --- ARCHITECTURE.md | 45 +++++++++++++++++++++++++++++++-------------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index dcfccfe7fd8..ad96e1937db 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -12,19 +12,21 @@ and more. ## Subcommands -Cargo is a single binary composed of a set of [`clap`][] subcommands. All subcommands live in +Cargo is a single binary composed of a set of [`clap`] subcommands. All subcommands live in `src/bin/cargo/commands` directory. `src/bin/cargo/main.rs` is the entry point. -Each subcommand, such as `src/bin/cargo/commands/build.rs`, has its own API +Each subcommand, such as [`src/bin/cargo/commands/build.rs`], has its own API interface, similarly to Git's, parsing command line options, reading the configuration files, discovering the Cargo project in the current directory and delegating the actual implementation to one -of the functions in `src/cargo/ops/mod.rs`. This short file is a good +of the functions in [`src/cargo/ops/mod.rs`]. This short file is a good place to find out about most of the things that Cargo can do. Subcommands are designed to pipe to one another, and custom subcommands make Cargo easy to extend and attach tools to. [`clap`]: https://clap.rs/ +[`src/bin/cargo/commands/build.rs`]: https://github.com/rust-lang/cargo/blob/master/src/bin/cargo/commands/build.rs +[`src/cargo/ops/mod.rs`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/mod.rs ## Important Data Structures @@ -32,15 +34,15 @@ Cargo easy to extend and attach tools to. There are some important data structures which are used throughout Cargo. -`Config` is available almost everywhere and holds "global" +[`Config`] is available almost everywhere and holds "global" information, such as `CARGO_HOME` or configuration from -`.cargo/config` files. The `shell` method of `Config` is the entry +`.cargo/config` files. The [`shell`] method of [`Config`] is the entry point for printing status messages and other info to the console. -`Workspace` is the description of the workspace for the current +[`Workspace`] is the description of the workspace for the current working directory. Each workspace contains at least one -`Package`. Each package corresponds to a single `Cargo.toml`, and may -define several `Target`s, such as the library, binaries, integration +[`Package`]. Each package corresponds to a single `Cargo.toml`, and may +define several [`Target`]s, such as the library, binaries, integration test or examples. Targets are crates (each target defines a crate root, like `src/lib.rs` or `examples/foo.rs`) and are what is actually compiled by `rustc`. @@ -50,18 +52,26 @@ auxiliary ones. Packages are a unit of dependency in Cargo, and when package `foo` depends on package `bar`, that means that each target from `foo` needs the library target from `bar`. -`PackageId` is the unique identifier of a (possibly remote) +[`PackageId`] is the unique identifier of a (possibly remote) package. It consist of three components: name, version and source id. Source is the place where the source code for package comes from. Typical sources are crates.io, a git repository or a folder on the local hard drive. -`Resolve` is the representation of a directed acyclic graph of package -dependencies, which uses `PackageId`s for nodes. This is the data +[`Resolve`] is the representation of a directed acyclic graph of package +dependencies, which uses [`PackageId`]s for nodes. This is the data structure that is saved to the lock file. If there is no lock file, Cargo constructs a resolve by finding a graph of packages which matches declared dependency specification according to semver. +[`Config`]: https://docs.rs/cargo/0.33.0/cargo/util/config/struct.Config.html +[`shell`]: https://docs.rs/cargo/0.33.0/cargo/util/config/struct.Config.html#method.shell +[`Workspace`]: https://docs.rs/cargo/0.33.0/cargo/core/struct.Workspace.html +[`Package`]: https://docs.rs/cargo/0.33.0/cargo/core/package/struct.Package.html +[`Target`]: https://docs.rs/cargo/0.33.0/cargo/core/manifest/struct.Target.html +[`PackageId`]: https://docs.rs/cargo/0.33.0/cargo/core/package_id/struct.PackageId.html +[`Resolve`]: https://docs.rs/cargo/0.33.0/cargo/core/struct.Resolve.html + ## Persistence @@ -70,9 +80,11 @@ the information used by Cargo must be persisted on the hard drive. The main sources of information are `Cargo.toml` and `Cargo.lock` files, `.cargo/config` configuration files and the globally shared registry of packages downloaded from crates.io, usually located at -`~/.cargo/registry`. See `src/sources/registry` for the specifics of +`~/.cargo/registry`. See [`src/cargo/sources/registry`] for the specifics of the registry storage format. +[`src/cargo/sources/registry`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources/registry + ## Concurrency @@ -108,15 +120,18 @@ p.cargo("run").stream().run(); Alternatively to build and run a custom version of cargo simply run `cargo build` and execute `target/debug/cargo`. Note that `+nightly`/`+stable` (and variants), -being [rustup](https://rustup.rs/) features, won't work when executing the locally +being [rustup] features, won't work when executing the locally built cargo binary directly, you have to instead build with `cargo +nightly build` and run with `rustup run` (e.g `rustup run nightly /target/debug/cargo ..`) (or set the `RUSTC` env var to point to nightly rustc). +[rustup]: https://rustup.rs/ + + ## Logging -Cargo uses [`env_logger`](https://docs.rs/env_logger/*/env_logger/), so you can set +Cargo uses [`env_logger`], so you can set `RUST_LOG` environment variable to get the logs. This is useful both for diagnosing bugs in stable Cargo and for local development. Cargo also has internal hierarchical profiling infrastructure, which is activated via `CARGO_PROFILE` variable @@ -131,3 +146,5 @@ $ RUST_LOG=cargo::core::resolver=trace cargo generate-lockfile # Output first three levels of profiling info $ CARGO_PROFILE=3 cargo generate-lockfile ``` + +[`env_logger`]: https://docs.rs/env_logger/*/env_logger/ From fea514a5f505ba3948160b58379fbd6e88500818 Mon Sep 17 00:00:00 2001 From: Hidehito Yabuuchi Date: Sat, 23 Feb 2019 23:09:36 +0900 Subject: [PATCH 2/3] Use relative links for links to repository itself --- ARCHITECTURE.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index ad96e1937db..cdd0b5666bb 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -25,8 +25,8 @@ Subcommands are designed to pipe to one another, and custom subcommands make Cargo easy to extend and attach tools to. [`clap`]: https://clap.rs/ -[`src/bin/cargo/commands/build.rs`]: https://github.com/rust-lang/cargo/blob/master/src/bin/cargo/commands/build.rs -[`src/cargo/ops/mod.rs`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/mod.rs +[`src/bin/cargo/commands/build.rs`]: src/bin/cargo/commands/build.rs +[`src/cargo/ops/mod.rs`]: src/cargo/ops/mod.rs ## Important Data Structures @@ -83,7 +83,7 @@ of packages downloaded from crates.io, usually located at `~/.cargo/registry`. See [`src/cargo/sources/registry`] for the specifics of the registry storage format. -[`src/cargo/sources/registry`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources/registry +[`src/cargo/sources/registry`]: src/cargo/sources/registry ## Concurrency From 85c5fe1fab98d76ef743ed1a8c7f5964c746e925 Mon Sep 17 00:00:00 2001 From: Hidehito Yabuuchi Date: Sun, 24 Feb 2019 12:21:08 +0900 Subject: [PATCH 3/3] Fix links to point the latest docs --- ARCHITECTURE.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index cdd0b5666bb..d73e69b1237 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -64,13 +64,13 @@ structure that is saved to the lock file. If there is no lock file, Cargo constructs a resolve by finding a graph of packages which matches declared dependency specification according to semver. -[`Config`]: https://docs.rs/cargo/0.33.0/cargo/util/config/struct.Config.html -[`shell`]: https://docs.rs/cargo/0.33.0/cargo/util/config/struct.Config.html#method.shell -[`Workspace`]: https://docs.rs/cargo/0.33.0/cargo/core/struct.Workspace.html -[`Package`]: https://docs.rs/cargo/0.33.0/cargo/core/package/struct.Package.html -[`Target`]: https://docs.rs/cargo/0.33.0/cargo/core/manifest/struct.Target.html -[`PackageId`]: https://docs.rs/cargo/0.33.0/cargo/core/package_id/struct.PackageId.html -[`Resolve`]: https://docs.rs/cargo/0.33.0/cargo/core/struct.Resolve.html +[`Config`]: https://docs.rs/cargo/latest/cargo/util/config/struct.Config.html +[`shell`]: https://docs.rs/cargo/latest/cargo/util/config/struct.Config.html#method.shell +[`Workspace`]: https://docs.rs/cargo/latest/cargo/core/struct.Workspace.html +[`Package`]: https://docs.rs/cargo/latest/cargo/core/package/struct.Package.html +[`Target`]: https://docs.rs/cargo/latest/cargo/core/manifest/struct.Target.html +[`PackageId`]: https://docs.rs/cargo/latest/cargo/core/package_id/struct.PackageId.html +[`Resolve`]: https://docs.rs/cargo/latest/cargo/core/struct.Resolve.html ## Persistence