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.