Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cargo book: source replacement #6865

Merged
merged 3 commits into from
Apr 29, 2019
Merged

Cargo book: source replacement #6865

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7ec8e9e
Git ignore built Cargo book.
Apr 22, 2019
6012657
Changes discussed in https://github.com/rust-lang/cargo/issues/6862
Apr 22, 2019
5526e10
Update with @ehuss suggestion
ehuss Apr 29, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/doc/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
# Ignore built book
book/
91 changes: 39 additions & 52 deletions src/doc/src/reference/source-replacement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,42 +4,9 @@ This document is about replacing the crate index. You can read about overriding
dependencies in the [overriding dependencies][overriding] section of this
documentation.

Cargo supports the ability to **replace one source with another** to express
strategies along the lines of mirrors or vendoring dependencies. Configuration
is currently done through the [`.cargo/config` configuration][config] mechanism,
like so:

[config]: reference/config.html

```toml
# The `source` table is where all keys related to source-replacement
# are stored.
[source]

# Under the `source` table are a number of other tables whose keys are a
# name for the relevant source. For example this section defines a new
# source, called `my-awesome-source`, which comes from a directory
# located at `vendor` relative to the directory containing this `.cargo/config`
# file
[source.my-awesome-source]
directory = "vendor"

# Git sources can optionally specify a branch/tag/rev as well
git = "https://example.com/path/to/repo"
# branch = "master"
# tag = "v1.0.1"
# rev = "313f44e8"

# The crates.io default source for crates is available under the name
# "crates-io", and here we use the `replace-with` key to indicate that it's
# replaced with our source above.
[source.crates-io]
replace-with = "my-awesome-source"
```

With this configuration Cargo attempts to look up all crates in the directory
"vendor" rather than querying the online registry at crates.io. Using source
replacement Cargo can express:
A *source* is a provider that contains crates that may be included as
dependencies for a package. Cargo supports the ability to **replace one source
with another** to express strategies such as:

* Vendoring - custom sources can be defined which represent crates on the local
filesystem. These sources are subsets of the source that they're replacing and
Expand All @@ -49,46 +16,64 @@ replacement Cargo can express:
cache for crates.io itself.

Cargo has a core assumption about source replacement that the source code is
exactly the same from both sources. In our above example Cargo assumes that all
of the crates coming from `my-awesome-source` are the exact same as the copies
from `crates-io`. Note that this also means that `my-awesome-source` is not
allowed to have crates which are not present in the `crates-io` source.
exactly the same from both sources. Note that this also means that
a replacement source is not allowed to have crates which are not present in the
default crates.io source.
fluffysquirrels marked this conversation as resolved.
Show resolved Hide resolved

As a consequence, source replacement is not appropriate for situations such as
patching a dependency or a private registry. Cargo supports patching
dependencies through the usage of [the `[replace]` key][replace-section], and
private registry support is planned for a future version of Cargo.
private registry support is described in [Registries][registries].

[replace-section]: reference/manifest.html#the-replace-section
[overriding]: reference/specifying-dependencies.html#overriding-dependencies
[registries]: reference/registries.html

### Configuration

Configuration of replacement sources is done through [`.cargo/config`][config]
and the full set of available keys are:

```toml
# The `source` table is where all keys related to source-replacement
# are stored.
[source]

# Under the `source` table are a number of other tables whose keys are a
# name for the relevant source. For example this section defines a new
# source, called `my-vendor-source`, which comes from a directory
# located at `vendor` relative to the directory containing this `.cargo/config`
# file
[source.my-vendor-source]
directory = "vendor"

# The crates.io default source for crates is available under the name
# "crates-io", and here we use the `replace-with` key to indicate that it's
# replaced with our source above.
[source.crates-io]
replace-with = "my-vendor-source"

# Each source has its own table where the key is the name of the source
[source.the-source-name]

# Indicate that `the-source-name` will be replaced with `another-source`,
# defined elsewhere
replace-with = "another-source"

# Available kinds of sources that can be specified (described below)
# Several kinds of sources can be specified (described in more detail below):
registry = "https://example.com/path/to/index"
local-registry = "path/to/registry"
directory = "path/to/vendor"
```

The `crates-io` represents the crates.io online registry (default source of
crates) and can be replaced with:

```toml
[source.crates-io]
replace-with = 'another-source'
# Git sources can optionally specify a branch/tag/rev as well
git = "https://example.com/path/to/repo"
# branch = "master"
# tag = "v1.0.1"
# rev = "313f44e8"
```

[config]: reference/config.html

### Registry Sources

A "registry source" is one that is the same as crates.io itself. That is, it has
Expand All @@ -107,8 +92,9 @@ are downloaded ahead of time, typically sync'd with a `Cargo.lock`, and are
made up of a set of `*.crate` files and an index like the normal registry is.

The primary way to manage and create local registry sources is through the
[`cargo-local-registry`][cargo-local-registry] subcommand, available on
crates.io and can be installed with `cargo install cargo-local-registry`.
[`cargo-local-registry`][cargo-local-registry] subcommand,
[available on crates.io][cargo-local-registry] and can be installed with
`cargo install cargo-local-registry`.

[cargo-local-registry]: https://crates.io/crates/cargo-local-registry

Expand All @@ -122,7 +108,8 @@ the crates that are present).
A "directory source" is similar to a local registry source where it contains a
number of crates available on the local filesystem, suitable for vendoring
dependencies. Also like local registries, directory sources can primarily be
managed by an external subcommand, [`cargo-vendor`][cargo-vendor], which can be
managed by an external subcommand, [`cargo-vendor`][cargo-vendor],
[available on crates.io][cargo-vendor] and can be
installed with `cargo install cargo-vendor`.

[cargo-vendor]: https://crates.io/crates/cargo-vendor
Expand Down