Source Replacement
This document is about replacing the crate index. You can read about overriding dependencies in the overriding dependencies section of this documentation.
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 can be checked into packages if necessary.
-
Mirroring - sources can be replaced with an equivalent version which acts as a cache for crates.io itself.
Cargo has a core assumption about source replacement that the source code is 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 original source.
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, and
private registry support is described in Registries.
Configuration
Configuration of replacement sources is done through .cargo/config
and the full set of available keys are:
# 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"
# 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"
# 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"
Registry Sources
A "registry source" is one that is the same as crates.io itself. That is, it has an index served in a git repository which matches the format of the crates.io index. That repository then has configuration indicating where to download crates from.
Currently there is not an already-available project for setting up a mirror of crates.io. Stay tuned though!
Local Registry Sources
A "local registry source" is intended to be a subset of another registry
source, but available on the local filesystem (aka vendoring). Local registries
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
subcommand,
available on crates.io and can be installed with
cargo install cargo-local-registry
.
Local registries are contained within one directory and contain a number of
*.crate
files downloaded from crates.io as well as an index
directory with
the same format as the crates.io-index project (populated with just entries for
the crates that are present).
Directory Sources
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
,
available on crates.io and can be
installed with cargo install cargo-vendor
.
Directory sources are distinct from local registries though in that they contain
the unpacked version of *.crate
files, making it more suitable in some
situations to check everything into source control. A directory source is just a
directory containing a number of other directories which contain the source code
for crates (the unpacked version of *.crate
files). Currently no restriction
is placed on the name of each directory.
Each crate in a directory source also has an associated metadata file indicating the checksum of each file in the crate to protect against accidental modifications.