Update “How can Cargo work offline?” FAQ section in Cargo book

[soloturn]

Problem

cargo flags --frozen and --offline are confusing. the cargo book says:

_As of Rust 1.11.0, Cargo understands a new flag, --frozen, which is an assertion that it shouldn’t touch the network. When passed, Cargo will immediately return an error if it would otherwise attempt a network request. The error should include contextual information about why the network request is being made in the first place to help debug as well. Note that this flag does not change the behavior of Cargo, it simply asserts that Cargo shouldn’t touch the network as a previous command has been run to ensure that network activity shouldn’t be necessary.

The --offline flag was added in Rust 1.36.0. This flag tells Cargo to not access the network, and try to proceed with available cached data if possible. You can use cargo fetch in one project to download dependencies before going offline, and then use those same dependencies in another project with the --offline flag (or configuration value)._

if you paste here a better description what the difference is i d create a pull request to adjust. if it is really the same, maybe drop one of the flags. it sounds weird that experienced programmers use both flags then, like COSMIC desktop build vendored with:
cargo build --release --frozen --offline

reference:

• https://github.com/pop-os/cosmic-applets/blob/master/debian/rules
• https://github.com/pop-os/cosmic-applets/blob/master/justfile

[ChrisDenton]

The documentation seems clear to me: https://doc.rust-lang.org/cargo/commands/cargo-build.html#manifest-options

--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:

• 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

Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and the network is not available. With this flag, Cargo will attempt to proceed without the network if possible.

Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. See the cargo-fetch(1) command to download dependencies before going offline.

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

--frozen

Equivalent to specifying both --locked and --offline.

Can you say what you find confusing?

[weihanglo]

Hmm… just realized they were talking about https://doc.rust-lang.org/cargo/faq.html#how-can-cargo-work-offline. That part needs to update to what ChrisDenton posted accordingly.