From fceff19ed2007480da65bd916816d17076666058 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Fri, 17 Mar 2023 01:11:41 -0500 Subject: [PATCH] docs(contrib): Pull impl info out of architecture Personally, I found mixing this stuff with architecture less than ideal as it buried the more practical information among details that might not have been as important. With us moving architecture information into doc comments, this provides us an opportunity to rectify this. Not a fan of the name of this chapter but its a start. I've left in the old architecture chapter as there is still content to find a home for (resolver). --- src/doc/contrib/src/SUMMARY.md | 8 ++++-- src/doc/contrib/src/architecture/files.md | 22 ---------------- .../contrib/src/architecture/filesystem.md | 1 + .../src/implementation/architecture.md | 5 ++++ .../console.md | 24 ----------------- .../contrib/src/implementation/debugging.md | 26 +++++++++++++++++++ .../contrib/src/implementation/filesystem.md | 21 +++++++++++++++ src/doc/contrib/src/implementation/index.md | 6 +++++ .../subcommands.md | 2 +- 9 files changed, 66 insertions(+), 49 deletions(-) create mode 100644 src/doc/contrib/src/architecture/filesystem.md create mode 100644 src/doc/contrib/src/implementation/architecture.md rename src/doc/contrib/src/{architecture => implementation}/console.md (75%) create mode 100644 src/doc/contrib/src/implementation/debugging.md create mode 100644 src/doc/contrib/src/implementation/filesystem.md create mode 100644 src/doc/contrib/src/implementation/index.md rename src/doc/contrib/src/{architecture => implementation}/subcommands.md (98%) diff --git a/src/doc/contrib/src/SUMMARY.md b/src/doc/contrib/src/SUMMARY.md index 20d790ee7de..046ab556e25 100644 --- a/src/doc/contrib/src/SUMMARY.md +++ b/src/doc/contrib/src/SUMMARY.md @@ -7,10 +7,14 @@ - [Release process](./process/release.md) - [Unstable features](./process/unstable.md) - [Design Principles](./design.md) +- [Implementing a Change](./implementation/index.md) + - [Architecture](./implementation/architecture.md) + - [New subcommands](./implementation/subcommands.md) + - [Console Output](./implementation/console.md) + - [Filesystem](./implementation/filesystem.md) + - [Debugging](./implementation/debugging.md) - [Architecture](./architecture/index.md) - [Codebase Overview](./architecture/codebase.md) - - [SubCommands](./architecture/subcommands.md) - - [Console Output](./architecture/console.md) - [Packages and Resolution](./architecture/packages.md) - [Compilation](./architecture/compilation.md) - [Files](./architecture/files.md) diff --git a/src/doc/contrib/src/architecture/files.md b/src/doc/contrib/src/architecture/files.md index 3d0632a5fde..2e430430a96 100644 --- a/src/doc/contrib/src/architecture/files.md +++ b/src/doc/contrib/src/architecture/files.md @@ -1,25 +1,3 @@ # Files See [nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html) - -## Filesystems - -Cargo tends to get run on a very wide array of file systems. Different file -systems can have a wide range of capabilities, and Cargo should strive to do -its best to handle them. Some examples of issues to deal with: - -* Not all file systems support locking. Cargo tries to detect if locking is - supported, and if not, will ignore lock errors. This isn't ideal, but it is - difficult to deal with. -* The [`fs::canonicalize`] function doesn't work on all file systems - (particularly some Windows file systems). If that function is used, there - should be a fallback if it fails. This function will also return `\\?\` - style paths on Windows, which can have some issues (such as some tools not - supporting them, or having issues with relative paths). -* Timestamps can be unreliable. The [`fingerprint`] module has a deeper - discussion of this. One example is that Docker cache layers will erase the - fractional part of the time stamp. -* Symlinks are not always supported, particularly on Windows. - -[`fingerprint`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs -[`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html diff --git a/src/doc/contrib/src/architecture/filesystem.md b/src/doc/contrib/src/architecture/filesystem.md new file mode 100644 index 00000000000..6d41ab86f00 --- /dev/null +++ b/src/doc/contrib/src/architecture/filesystem.md @@ -0,0 +1 @@ +# Filesystem diff --git a/src/doc/contrib/src/implementation/architecture.md b/src/doc/contrib/src/implementation/architecture.md new file mode 100644 index 00000000000..b712c4fe501 --- /dev/null +++ b/src/doc/contrib/src/implementation/architecture.md @@ -0,0 +1,5 @@ +# Architecture Overview + +See the +[nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo/index.html) +for an overview of `cargo`s architecture and links out to further details. diff --git a/src/doc/contrib/src/architecture/console.md b/src/doc/contrib/src/implementation/console.md similarity index 75% rename from src/doc/contrib/src/architecture/console.md rename to src/doc/contrib/src/implementation/console.md index 2c5412b8c46..a73d232e0ce 100644 --- a/src/doc/contrib/src/architecture/console.md +++ b/src/doc/contrib/src/implementation/console.md @@ -55,28 +55,4 @@ Some guidelines for Cargo's output: and use multiple sentences. This should probably be improved sometime in the future to be more structured. -## Debug logging - -Cargo uses the [`env_logger`] crate to display debug log messages. The -`CARGO_LOG` environment variable can be set to enable debug logging, with a -value such as `trace`, `debug`, or `warn`. It also supports filtering for -specific modules. Feel free to use the standard [`log`] macros to help with -diagnosing problems. - -```sh -# Outputs all logs with levels debug and higher -CARGO_LOG=debug cargo generate-lockfile - -# Don't forget that you can filter by module as well -CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile - -# This will print lots of info about the download process. `trace` prints even more. -CARGO_HTTP_DEBUG=true CARGO_LOG=cargo::ops::registry=debug cargo fetch - -# This is an important command for diagnosing fingerprint issues. -CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build -``` - -[`env_logger`]: https://docs.rs/env_logger -[`log`]: https://docs.rs/log [`anyhow`]: https://docs.rs/anyhow diff --git a/src/doc/contrib/src/implementation/debugging.md b/src/doc/contrib/src/implementation/debugging.md new file mode 100644 index 00000000000..e148d72c36b --- /dev/null +++ b/src/doc/contrib/src/implementation/debugging.md @@ -0,0 +1,26 @@ +# Debugging + +## Logging + +Cargo uses the [`env_logger`] crate to display debug log messages. The +`CARGO_LOG` environment variable can be set to enable debug logging, with a +value such as `trace`, `debug`, or `warn`. It also supports filtering for +specific modules. Feel free to use the standard [`log`] macros to help with +diagnosing problems. + +```sh +# Outputs all logs with levels debug and higher +CARGO_LOG=debug cargo generate-lockfile + +# Don't forget that you can filter by module as well +CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile + +# This will print lots of info about the download process. `trace` prints even more. +CARGO_HTTP_DEBUG=true CARGO_LOG=cargo::ops::registry=debug cargo fetch + +# This is an important command for diagnosing fingerprint issues. +CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build +``` + +[`env_logger`]: https://docs.rs/env_logger +[`log`]: https://docs.rs/log diff --git a/src/doc/contrib/src/implementation/filesystem.md b/src/doc/contrib/src/implementation/filesystem.md new file mode 100644 index 00000000000..0f70c5833f0 --- /dev/null +++ b/src/doc/contrib/src/implementation/filesystem.md @@ -0,0 +1,21 @@ +# Filesystem + +Cargo tends to get run on a very wide array of file systems. Different file +systems can have a wide range of capabilities, and Cargo should strive to do +its best to handle them. Some examples of issues to deal with: + +* Not all file systems support locking. Cargo tries to detect if locking is + supported, and if not, will ignore lock errors. This isn't ideal, but it is + difficult to deal with. +* The [`fs::canonicalize`] function doesn't work on all file systems + (particularly some Windows file systems). If that function is used, there + should be a fallback if it fails. This function will also return `\\?\` + style paths on Windows, which can have some issues (such as some tools not + supporting them, or having issues with relative paths). +* Timestamps can be unreliable. The [`fingerprint`] module has a deeper + discussion of this. One example is that Docker cache layers will erase the + fractional part of the time stamp. +* Symlinks are not always supported, particularly on Windows. + +[`fingerprint`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs +[`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html diff --git a/src/doc/contrib/src/implementation/index.md b/src/doc/contrib/src/implementation/index.md new file mode 100644 index 00000000000..ad7c80d5e8b --- /dev/null +++ b/src/doc/contrib/src/implementation/index.md @@ -0,0 +1,6 @@ +# Implementing a Change + +This chapter gives an overview of what you need to know in making a change to cargo. + +If you feel something is missing that would help you, feel free to ask on +[Zulip](https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo). diff --git a/src/doc/contrib/src/architecture/subcommands.md b/src/doc/contrib/src/implementation/subcommands.md similarity index 98% rename from src/doc/contrib/src/architecture/subcommands.md rename to src/doc/contrib/src/implementation/subcommands.md index bdb586c24ed..9f5da35550f 100644 --- a/src/doc/contrib/src/architecture/subcommands.md +++ b/src/doc/contrib/src/implementation/subcommands.md @@ -1,4 +1,4 @@ -# SubCommands +# New Subcommands Cargo is a single binary composed of a set of [`clap`] subcommands. All subcommands live in [`src/bin/cargo/commands`] directory.