From d1e72bca74e81978e1af561cbf28cf423f1bdebc Mon Sep 17 00:00:00 2001 From: Weihang Lo Date: Thu, 1 Aug 2024 09:00:52 -0400 Subject: [PATCH] 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