Source Replacement

This document is about replacing the crate index. You can read about overridingdependencies in the overriding dependencies section of thisdocumentation.

A source is a provider that contains crates that may be included asdependencies for a package. Cargo supports the ability to replace one sourcewith another to express strategies such as:

  • Vendoring - custom sources can be defined which represent crates on the localfilesystem. These sources are subsets of the source that they're replacing andcan be checked into packages if necessary.

  • Mirroring - sources can be replaced with an equivalent version which acts as acache for crates.io itself.

Cargo has a core assumption about source replacement that the source code isexactly the same from both sources. Note that this also means thata replacement source is not allowed to have crates which are not present in theoriginal source.

As a consequence, source replacement is not appropriate for situations such aspatching a dependency or a private registry. Cargo supports patchingdependencies through the usage of the [replace] key, andprivate registry support is described in Registries.

Configuration

Configuration of replacement sources is done through .cargo/configand the full set of available keys are:

  1. # The `source` table is where all keys related to source-replacement
  2. # are stored.
  3. [source]
  5. # Under the `source` table are a number of other tables whose keys are a
  6. # name for the relevant source. For example this section defines a new
  7. # source, called `my-vendor-source`, which comes from a directory
  8. # located at `vendor` relative to the directory containing this `.cargo/config`
  9. # file
  10. [source.my-vendor-source]
  11. directory = "vendor"
  13. # The crates.io default source for crates is available under the name
  14. # "crates-io", and here we use the `replace-with` key to indicate that it's
  15. # replaced with our source above.
  16. [source.crates-io]
  17. replace-with = "my-vendor-source"
  19. # Each source has its own table where the key is the name of the source
  20. [source.the-source-name]
  22. # Indicate that `the-source-name` will be replaced with `another-source`,
  23. # defined elsewhere
  24. replace-with = "another-source"
  26. # Several kinds of sources can be specified (described in more detail below):
  27. registry = "https://example.com/path/to/index"
  28. local-registry = "path/to/registry"
  29. directory = "path/to/vendor"
  31. # Git sources can optionally specify a branch/tag/rev as well
  32. git = "https://example.com/path/to/repo"
  33. # branch = "master"
  34. # tag = "v1.0.1"
  35. # rev = "313f44e8"

Registry Sources

A "registry source" is one that is the same as crates.io itself. That is, it hasan index served in a git repository which matches the format of thecrates.io index. That repositorythen has configuration indicating where to download crates from.

Currently there is not an already-available project for setting up a mirror ofcrates.io. Stay tuned though!

Local Registry Sources

A "local registry source" is intended to be a subset of another registrysource, but available on the local filesystem (aka vendoring). Local registriesare downloaded ahead of time, typically sync'd with a Cargo.lock, and aremade 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 thecargo-local-registry subcommand,available on crates.io and can be installed withcargo 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 withthe same format as the crates.io-index project (populated with just entries forthe crates that are present).

Directory Sources

A "directory source" is similar to a local registry source where it contains anumber of crates available on the local filesystem, suitable for vendoringdependencies. Directory sources are primarily managed the cargo vendorsubcommand.

Directory sources are distinct from local registries though in that they containthe unpacked version of .crate files, making it more suitable in somesituations to check everything into source control. A directory source is just adirectory containing a number of other directories which contain the source codefor crates (the unpacked version of .crate files). Currently no restrictionis placed on the name of each directory.

Each crate in a directory source also has an associated metadata file indicatingthe checksum of each file in the crate to protect against accidentalmodifications.