1## Source Replacement 2 3This document is about replacing the crate index. You can read about overriding 4dependencies in the [overriding dependencies] section of this 5documentation. 6 7A *source* is a provider that contains crates that may be included as 8dependencies for a package. Cargo supports the ability to **replace one source 9with another** to express strategies such as: 10 11* Vendoring - custom sources can be defined which represent crates on the local 12 filesystem. These sources are subsets of the source that they're replacing and 13 can be checked into packages if necessary. 14 15* Mirroring - sources can be replaced with an equivalent version which acts as a 16 cache for crates.io itself. 17 18Cargo has a core assumption about source replacement that the source code is 19exactly the same from both sources. Note that this also means that 20a replacement source is not allowed to have crates which are not present in the 21original source. 22 23As a consequence, source replacement is not appropriate for situations such as 24patching a dependency or a private registry. Cargo supports patching 25dependencies through the usage of [the `[patch]` key][overriding 26dependencies], and private registry support is described in [the Registries 27chapter][registries]. 28 29[overriding dependencies]: overriding-dependencies.md 30[registries]: registries.md 31 32### Configuration 33 34Configuration of replacement sources is done through [`.cargo/config.toml`][config] 35and the full set of available keys are: 36 37```toml 38# The `source` table is where all keys related to source-replacement 39# are stored. 40[source] 41 42# Under the `source` table are a number of other tables whose keys are a 43# name for the relevant source. For example this section defines a new 44# source, called `my-vendor-source`, which comes from a directory 45# located at `vendor` relative to the directory containing this `.cargo/config.toml` 46# file 47[source.my-vendor-source] 48directory = "vendor" 49 50# The crates.io default source for crates is available under the name 51# "crates-io", and here we use the `replace-with` key to indicate that it's 52# replaced with our source above. 53[source.crates-io] 54replace-with = "my-vendor-source" 55 56# Each source has its own table where the key is the name of the source 57[source.the-source-name] 58 59# Indicate that `the-source-name` will be replaced with `another-source`, 60# defined elsewhere 61replace-with = "another-source" 62 63# Several kinds of sources can be specified (described in more detail below): 64registry = "https://example.com/path/to/index" 65local-registry = "path/to/registry" 66directory = "path/to/vendor" 67 68# Git sources can optionally specify a branch/tag/rev as well 69git = "https://example.com/path/to/repo" 70# branch = "master" 71# tag = "v1.0.1" 72# rev = "313f44e8" 73``` 74 75[config]: config.md 76 77### Registry Sources 78 79A "registry source" is one that is the same as crates.io itself. That is, it has 80an index served in a git repository which matches the format of the 81[crates.io index](https://github.com/rust-lang/crates.io-index). That repository 82then has configuration indicating where to download crates from. 83 84Currently there is not an already-available project for setting up a mirror of 85crates.io. Stay tuned though! 86 87### Local Registry Sources 88 89A "local registry source" is intended to be a subset of another registry 90source, but available on the local filesystem (aka vendoring). Local registries 91are downloaded ahead of time, typically sync'd with a `Cargo.lock`, and are 92made up of a set of `*.crate` files and an index like the normal registry is. 93 94The primary way to manage and create local registry sources is through the 95[`cargo-local-registry`][cargo-local-registry] subcommand, 96[available on crates.io][cargo-local-registry] and can be installed with 97`cargo install cargo-local-registry`. 98 99[cargo-local-registry]: https://crates.io/crates/cargo-local-registry 100 101Local registries are contained within one directory and contain a number of 102`*.crate` files downloaded from crates.io as well as an `index` directory with 103the same format as the crates.io-index project (populated with just entries for 104the crates that are present). 105 106### Directory Sources 107 108A "directory source" is similar to a local registry source where it contains a 109number of crates available on the local filesystem, suitable for vendoring 110dependencies. Directory sources are primarily managed by the `cargo vendor` 111subcommand. 112 113Directory sources are distinct from local registries though in that they contain 114the unpacked version of `*.crate` files, making it more suitable in some 115situations to check everything into source control. A directory source is just a 116directory containing a number of other directories which contain the source code 117for crates (the unpacked version of `*.crate` files). Currently no restriction 118is placed on the name of each directory. 119 120Each crate in a directory source also has an associated metadata file indicating 121the checksum of each file in the crate to protect against accidental 122modifications. 123