Skip to content

Commit

Permalink
Auto merge of #14336 - soloturn:master, r=weihanglo
Browse files Browse the repository at this point in the history
faq: rephrase offline usage.

### What does this PR try to resolve?
fixes #14330. FAQ tried to explain the history of cargo offline, and thus
was distracting from the core flags.
  • Loading branch information
bors committed Aug 2, 2024
2 parents 5ff9328 + 16540c2 commit e5ec01c
Showing 1 changed file with 13 additions and 38 deletions.
51 changes: 13 additions & 38 deletions src/doc/src/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit e5ec01c

Please sign in to comment.