From d1e72bca74e81978e1af561cbf28cf423f1bdebc Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Thu, 1 Aug 2024 09:00:52 -0400 Subject: [PATCH 1/2] fix: also build manpage for `cargo.md` --- crates/xtask-build-man/src/main.rs | 4 ++-- src/doc/man/generated_txt/cargo.txt | 24 +++++++++++++++--------- src/doc/src/commands/cargo.md | 24 ++++++++++++------------ src/etc/man/cargo.1 | 26 ++++++++++++++++++-------- 4 files changed, 47 insertions(+), 31 deletions(-) diff --git a/crates/xtask-build-man/src/main.rs b/crates/xtask-build-man/src/main.rs index 2ab3f098aaa..646610d5fa5 100644 --- a/crates/xtask-build-man/src/main.rs +++ b/crates/xtask-build-man/src/main.rs @@ -45,14 +45,14 @@ fn build_mdman() -> io::Result<()> { /// saved in the src/doc/src/commands/ directory. These are included in the /// Cargo book, which is converted to HTML by mdbook. fn build_cargo() -> io::Result<()> { - // Find all `src/doc/man/cargo-*.md` + // Find all `src/doc/man/cargo*.md` let src_paths = { let mut src_paths = Vec::new(); for entry in fs::read_dir("src/doc/man")? { let entry = entry?; let file_name = entry.file_name(); let file_name = file_name.to_str().unwrap(); - if file_name.starts_with("cargo-") && file_name.ends_with(".md") { + if file_name.starts_with("cargo") && file_name.ends_with(".md") { src_paths.push(entry.path()); } } diff --git a/src/doc/man/generated_txt/cargo.txt b/src/doc/man/generated_txt/cargo.txt index 5c0762e6038..ce12de58c79 100644 --- a/src/doc/man/generated_txt/cargo.txt +++ b/src/doc/man/generated_txt/cargo.txt @@ -158,16 +158,19 @@ OPTIONS . Manifest Options - --frozen, --locked - Either of these flags requires that the Cargo.lock file is - up-to-date. If the lock file is missing, or it needs to be updated, - Cargo will exit with an error. The --frozen flag also prevents Cargo - from attempting to access the network to determine if it is - out-of-date. + --locked + Asserts that the exact same dependencies and versions are used as + when the existing Cargo.lock file was originally generated. Cargo + will exit with an error when either of the following scenarios + arises: - These may be used in environments where you want to assert that the - Cargo.lock file is up-to-date (such as a CI build) or want to avoid - network access. + o The lock file is missing. + + o Cargo attempted to change the lock file due to a different + dependency resolution. + + It may be used in environments where deterministic builds are + desired, such as in CI pipelines. --offline Prevents Cargo from accessing the network for any reason. Without @@ -184,6 +187,9 @@ OPTIONS May also be specified with the net.offline config value . + --frozen + Equivalent to specifying both --locked and --offline. + Common Options +toolchain If Cargo has been installed with rustup, and the first argument to diff --git a/src/doc/src/commands/cargo.md b/src/doc/src/commands/cargo.md index b1b07bc7021..bd1eafa183c 100644 --- a/src/doc/src/commands/cargo.md +++ b/src/doc/src/commands/cargo.md @@ -180,21 +180,21 @@ terminal. config value. - ### Manifest Options
-
--frozen
--locked
-
Either of these flags requires that the Cargo.lock file is -up-to-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The --frozen flag also prevents Cargo from -attempting to access the network to determine if it is out-of-date.

-

These may be used in environments where you want to assert that the -Cargo.lock file is up-to-date (such as a CI build) or want to avoid network -access.

+
Asserts that the exact same dependencies and versions are used as when the +existing Cargo.lock file was originally generated. Cargo will exit with an +error when either of the following scenarios arises:

+
    +
  • The lock file is missing.
    • +
  • Cargo attempted to change the lock file due to a different dependency resolution.
    • +
+

It may be used in environments where deterministic builds are desired, +such as in CI pipelines.

--offline
@@ -210,6 +210,9 @@ offline.

May also be specified with the net.offline config value. +

--frozen
+
Equivalent to specifying both --locked and --offline.
+
### Common Options @@ -252,19 +255,16 @@ requires the -Z unstable-options flag to enable (see - ## ENVIRONMENT See [the reference](../reference/environment-variables.html) for details on environment variables that Cargo reads. - ## EXIT STATUS * `0`: Cargo succeeded. * `101`: Cargo failed to complete. - ## FILES `~/.cargo/`\ diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 index 8f61e0699f2..fd6e43be66f 100644 --- a/src/etc/man/cargo.1 +++ b/src/etc/man/cargo.1 @@ -209,17 +209,22 @@ May also be specified with the \fBterm.color\fR .RE .SS "Manifest Options" .sp -\fB\-\-frozen\fR, \fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fR file is -up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from -attempting to access the network to determine if it is out\-of\-date. +Asserts that the exact same dependencies and versions are used as when the +existing \fBCargo.lock\fR file was originally generated. Cargo will exit with an +error when either of the following scenarios arises: .sp -These may be used in environments where you want to assert that the -\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network -access. +.RS 4 +\h'-04'\(bu\h'+02'The lock file is missing. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Cargo attempted to change the lock file due to a different dependency resolution. +.RE +.sp +It may be used in environments where deterministic builds are desired, +such as in CI pipelines. .RE .sp \fB\-\-offline\fR @@ -237,6 +242,11 @@ offline. .sp May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE +.sp +\fB\-\-frozen\fR +.RS 4 +Equivalent to specifying both \fB\-\-locked\fR and \fB\-\-offline\fR\&. +.RE .SS "Common Options" .sp \fB+\fR\fItoolchain\fR From 96767be00dd5ca35e1874e5cd0f5ccb7801ba2b7 Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Thu, 1 Aug 2024 09:11:40 -0400 Subject: [PATCH 2/2] docs: add missing cargo-add and cargo-rm --- src/doc/man/cargo.md | 6 ++++++ src/doc/man/generated_txt/cargo.txt | 6 ++++++ src/doc/src/commands/cargo.md | 6 ++++++ src/etc/man/cargo.1 | 8 ++++++++ 4 files changed, 26 insertions(+) diff --git a/src/doc/man/cargo.md b/src/doc/man/cargo.md index 3b1c62e3253..fa3d8bd3bc7 100644 --- a/src/doc/man/cargo.md +++ b/src/doc/man/cargo.md @@ -56,6 +56,9 @@ available at . ### Manifest Commands +{{man "cargo-add" 1}}\ +    Add dependencies to a `Cargo.toml` manifest file. + {{man "cargo-generate-lockfile" 1}}\     Generate `Cargo.lock` for a project. @@ -68,6 +71,9 @@ available at . {{man "cargo-pkgid" 1}}\     Print a fully qualified package specification. +{{man "cargo-remove" 1}}\ +    Remove dependencies from a `Cargo.toml` manifest file. + {{man "cargo-tree" 1}}\     Display a tree visualization of a dependency graph. diff --git a/src/doc/man/generated_txt/cargo.txt b/src/doc/man/generated_txt/cargo.txt index ce12de58c79..d9a1d1fd7af 100644 --- a/src/doc/man/generated_txt/cargo.txt +++ b/src/doc/man/generated_txt/cargo.txt @@ -50,6 +50,9 @@ COMMANDS     Execute unit and integration tests of a package. Manifest Commands + cargo-add(1) +     Add dependencies to a Cargo.toml manifest file. + cargo-generate-lockfile(1)     Generate Cargo.lock for a project. @@ -63,6 +66,9 @@ COMMANDS cargo-pkgid(1)     Print a fully qualified package specification. + cargo-remove(1) +     Remove dependencies from a Cargo.toml manifest file. + cargo-tree(1)     Display a tree visualization of a dependency graph. diff --git a/src/doc/src/commands/cargo.md b/src/doc/src/commands/cargo.md index bd1eafa183c..ccba5dc446b 100644 --- a/src/doc/src/commands/cargo.md +++ b/src/doc/src/commands/cargo.md @@ -56,6 +56,9 @@ available at . ### Manifest Commands +[cargo-add(1)](cargo-add.html)\ +    Add dependencies to a `Cargo.toml` manifest file. + [cargo-generate-lockfile(1)](cargo-generate-lockfile.html)\     Generate `Cargo.lock` for a project. @@ -68,6 +71,9 @@ available at . [cargo-pkgid(1)](cargo-pkgid.html)\     Print a fully qualified package specification. +[cargo-remove(1)](cargo-remove.html)\ +    Remove dependencies from a `Cargo.toml` manifest file. + [cargo-tree(1)](cargo-tree.html)\     Display a tree visualization of a dependency graph. diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 index fd6e43be66f..eebcf89e43d 100644 --- a/src/etc/man/cargo.1 +++ b/src/etc/man/cargo.1 @@ -64,6 +64,10 @@ available at \&. .br \ \ \ \ Execute unit and integration tests of a package. .SS "Manifest Commands" +\fBcargo\-add\fR(1) +.br +\ \ \ \ Add dependencies to a \fBCargo.toml\fR manifest file. +.sp \fBcargo\-generate\-lockfile\fR(1) .br \ \ \ \ Generate \fBCargo.lock\fR for a project. @@ -80,6 +84,10 @@ available at \&. .br \ \ \ \ Print a fully qualified package specification. .sp +\fBcargo\-remove\fR(1) +.br +\ \ \ \ Remove dependencies from a \fBCargo.toml\fR manifest file. +.sp \fBcargo\-tree\fR(1) .br \ \ \ \ Display a tree visualization of a dependency graph.