Skip to content

Commit 63ac9e1

Browse files
alexcrichtonalexcrichton
committed
Add documentation for source replacement
1 parent 4814a84 commit 63ac9e1

File tree

4 files changed

+134
-3
lines changed

4 files changed

+134
-3
lines changed

‎Makefile.in

+1-1
Original file line numberDiff line numberDiff line change
@@ -136,7 +136,7 @@ clean:
136136
# === Documentation
137137

138138
DOCS := index faq config guide manifest build-script pkgid-spec crates-io \
139-
environment-variables specifying-dependencies
139+
environment-variables specifying-dependencies source-replacement
140140
DOC_DIR := target/doc
141141
DOC_OPTS := --markdown-no-toc \
142142
--markdown-css stylesheets/normalize.css \

‎src/doc/faq.md

+4-2
Original file line numberDiff line numberDiff line change
@@ -187,5 +187,7 @@ that this flag *does not change the behavior of Cargo*, it simply asserts that
187187
Cargo shouldn't touch the network as a previous command has been run to ensure
188188
that network activity shouldn't be necessary.
189189

190-
Note that Cargo does not yet support vendoring in a first-class fashion, but
191-
this is a hotly desired feature and coming soon!
190+
For more information about vendoring, see documentation on [source
191+
replacement][replace].
192+
193+
[replace]: source-replacement.html

‎src/doc/header.html

+1
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ <h1>CARGO</h1>
3838
<li><a href='config.html'>Configuration</a></li>
3939
<li><a href='pkgid-spec.html'>Package ID specs</a></li>
4040
<li><a href='environment-variables.html'>Environment Variables</a></li>
41+
<li><a href='source-replacement.html'>Source Replacement</a></li>
4142
</ul>
4243
</div>
4344
</div>

‎src/doc/source-replacement.md

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

0 commit comments

Comments
 (0)