From 16540c2be6a83bcedaf80b96e32ba66a34f9ad61 Mon Sep 17 00:00:00 2001 From: soloturn Date: Thu, 1 Aug 2024 09:26:03 +0200 Subject: [PATCH] faq: rephrase offline usage. link flags, fixes #14330. Co-authored-by: Weihang Lo --- src/doc/src/faq.md | 51 ++++++++++++---------------------------------- 1 file changed, 13 insertions(+), 38 deletions(-) diff --git a/src/doc/src/faq.md b/src/doc/src/faq.md index e4206481cd0..8c907fbce58 100644 --- a/src/doc/src/faq.md +++ b/src/doc/src/faq.md @@ -131,8 +131,8 @@ verified against consistent versions of dependencies, like when However, this determinism can give a false sense of security because `Cargo.lock` does not affect the consumers of your package, only `Cargo.toml` does that. For example: -- [`cargo install`] will select the latest dependencies unless `--locked` is - passed in. +- [`cargo install`] will select the latest dependencies unless + `[--locked`](commands/cargo.html#option-cargo---locked) is passed in. - New dependencies, like those added with [`cargo add`], will be locked to the latest version The lockfile can also be a source of merge conflicts. @@ -174,42 +174,17 @@ but others were accidentally forgotten. ## How can Cargo work offline? -Cargo is often used in situations with limited or no network access such as -airplanes, CI environments, or embedded in large production deployments. Users -are often surprised when Cargo attempts to fetch resources from the network, and -hence the request for Cargo to work offline comes up frequently. - -Cargo, at its heart, will not attempt to access the network unless told to do -so. That is, if no crates come from crates.io, a git repository, or some other -network location, Cargo will never attempt to make a network connection. As a -result, if Cargo attempts to touch the network, then it's because it needs to -fetch a required resource. - -Cargo is also quite aggressive about caching information to minimize the amount -of network activity. It will guarantee, for example, that if `cargo build` (or -an equivalent) is run to completion then the next `cargo build` is guaranteed to -not touch the network so long as `Cargo.toml` has not been modified in the -meantime. This avoidance of the network boils down to a `Cargo.lock` existing -and a populated cache of the crates reflected in the lock file. If either of -these components are missing, then they're required for the build to succeed and -must be fetched remotely. - -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][offline config]). - -For more information about vendoring, see documentation on [source +The [`--offline`](commands/cargo.html#option-cargo---offline) or + [`--frozen`](commands/cargo.html#option-cargo---frozen) flags tell Cargo to not + touch the network. It returns an error in case it would access the network. +You can use [`cargo fetch`] in one project to download +dependencies before going offline, and then use those same dependencies in +another project. Refer to [configuration value][offline config]) to set via +Cargo configuration. + + + +Vendoring is also related, for more information see documentation on [source replacement][replace]. [replace]: reference/source-replacement.md