diff --git a/src/doc/man/cargo-fix.adoc b/src/doc/man/cargo-fix.adoc
index 2a7ff56a64f..0cc8c3da4f8 100644
--- a/src/doc/man/cargo-fix.adoc
+++ b/src/doc/man/cargo-fix.adoc
@@ -28,14 +28,18 @@ executing:
cargo fix --edition
-which behaves the same as `cargo check --all-targets`. Similarly if you'd like
-to fix code for different platforms you can do:
+which behaves the same as `cargo check --all-targets`.
- cargo fix --edition --target x86_64-pc-windows-gnu
+`cargo fix` is only capable of fixing code that is normally compiled with
+`cargo check`. If code is conditionally enabled with optional features, you
+will need to enable those features for that code to be analyzed:
+
+ cargo fix --edition --features foo
-or if your crate has optional features:
+Similarly, other `cfg` expressions like platform-specific code will need to
+pass `--target` to fix code for the given target.
- cargo fix --edition --no-default-features --features foo
+ cargo fix --edition --target x86_64-pc-windows-gnu
If you encounter any problems with `cargo fix` or otherwise have any questions
or feature requests please don't hesitate to file an issue at
diff --git a/src/doc/man/cargo-package.adoc b/src/doc/man/cargo-package.adoc
index 788f55f9b0d..ba1c1b5d69a 100644
--- a/src/doc/man/cargo-package.adoc
+++ b/src/doc/man/cargo-package.adoc
@@ -33,6 +33,9 @@ steps:
about the current VCS checkout hash if available (not included with
`--allow-dirty`).
. Extract the `.crate` file and build it to verify it can build.
+ - This will rebuild your package from scratch to ensure that it can be
+ built from a pristine state. The `--no-verify` flag can be used to skip
+ this step.
. Check that build scripts did not modify any source files.
The list of files included can be controlled with the `include` and `exclude`
diff --git a/src/doc/man/cargo-rustc.adoc b/src/doc/man/cargo-rustc.adoc
index 7ba60cb19e1..e3ef3e5fc72 100644
--- a/src/doc/man/cargo-rustc.adoc
+++ b/src/doc/man/cargo-rustc.adoc
@@ -25,8 +25,8 @@ flags.
include::description-one-target.adoc[]
To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS`
-environment variable or the `build.rustflags`
-linkcargo:reference/config.html[config value].
+linkcargo:reference/environment-variables.html[environment variable] or the
+`build.rustflags` linkcargo:reference/config.html[config value].
== OPTIONS
diff --git a/src/doc/man/cargo-rustdoc.adoc b/src/doc/man/cargo-rustdoc.adoc
index 61dfcb413db..96f37252aaa 100644
--- a/src/doc/man/cargo-rustdoc.adoc
+++ b/src/doc/man/cargo-rustdoc.adoc
@@ -25,8 +25,8 @@ flags.
include::description-one-target.adoc[]
To pass flags to all rustdoc processes spawned by Cargo, use the
-`RUSTDOCFLAGS` environment variable or the `build.rustdocflags` configuration
-option.
+`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable]
+or the `build.rustdocflags` linkcargo:reference/config.html[config value].
== OPTIONS
diff --git a/src/doc/man/generated/cargo-bench.html b/src/doc/man/generated/cargo-bench.html
index c6e03d01ca5..c25ebe82798 100644
--- a/src/doc/man/generated/cargo-bench.html
+++ b/src/doc/man/generated/cargo-bench.html
@@ -213,7 +213,8 @@
Feature Selection
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -241,6 +242,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -170,6 +171,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -174,6 +175,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -152,6 +153,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
which behaves the same as cargo check --all-targets. Similarly if you’d like
-to fix code for different platforms you can do:
+
which behaves the same as cargo check --all-targets.
+
+
+
cargo fix is only capable of fixing code that is normally compiled with
+cargo check. If code is conditionally enabled with optional features, you
+will need to enable those features for that code to be analyzed:
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -245,6 +251,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -240,6 +241,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
Extract the .crate file and build it to verify it can build.
+
+
+
+
This will rebuild your package from scratch to ensure that it can be
+built from a pristine state. The --no-verify flag can be used to skip
+this step.
+
+
+
Check that build scripts did not modify any source files.
@@ -117,6 +126,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
+
--target-dirDIRECTORY
@@ -140,7 +154,8 @@
Feature Selection
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
+
--target-dirDIRECTORY
@@ -133,7 +138,8 @@
Feature Selection
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -104,6 +105,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
package the filters of --lib, --bin, etc, must be used to select which
target is compiled.
To pass flags to all compiler processes spawned by Cargo, use the RUSTFLAGS
-environment variable or the build.rustflags
-config value.
+environment variable or the
+build.rustflagsconfig value.
@@ -137,7 +137,8 @@
Feature Selection
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -165,6 +166,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
package the filters of --lib, --bin, etc, must be used to select which
target is compiled.
To pass flags to all rustdoc processes spawned by Cargo, use the
-RUSTDOCFLAGS environment variable or the build.rustdocflags configuration
-option.
+RUSTDOCFLAGSenvironment variable
+or the build.rustdocflagsconfig value.
@@ -152,7 +152,8 @@
Feature Selection
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -180,6 +181,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
Space or comma separated list of features to activate. These features only
apply to the current directory’s package. Features of direct dependencies
-may be enabled with <dep-name>/<feature-name> syntax.
+may be enabled with <dep-name>/<feature-name> syntax. This flag may be
+specified multiple times, which enables all specified features.
--all-features
@@ -261,6 +262,11 @@
Compilation Options
This may also be specified with the build.targetconfig value.
+
+
Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+build cache documentation for more details.
+
--release
diff --git a/src/doc/man/options-features.adoc b/src/doc/man/options-features.adoc
index 666ef21e4ec..d9294e2d410 100644
--- a/src/doc/man/options-features.adoc
+++ b/src/doc/man/options-features.adoc
@@ -6,7 +6,8 @@ every selected package.
*--features* _FEATURES_::
Space or comma separated list of features to activate. These features only
apply to the current directory's package. Features of direct dependencies
- may be enabled with `/` syntax.
+ may be enabled with `/` syntax. This flag may be
+ specified multiple times, which enables all specified features.
*--all-features*::
Activate all available features of all selected packages.
diff --git a/src/doc/man/options-target-triple.adoc b/src/doc/man/options-target-triple.adoc
index eac97d88505..9cb6d7c85e5 100644
--- a/src/doc/man/options-target-triple.adoc
+++ b/src/doc/man/options-target-triple.adoc
@@ -6,3 +6,7 @@
+
This may also be specified with the `build.target`
linkcargo:reference/config.html[config value].
++
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+linkcargo:guide/build-cache.html[build cache] documentation for more details.
diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md
index 8a1ca888bc7..b77fce9ed52 100644
--- a/src/doc/src/SUMMARY.md
+++ b/src/doc/src/SUMMARY.md
@@ -20,7 +20,11 @@
* [Cargo Reference](reference/index.md)
* [Specifying Dependencies](reference/specifying-dependencies.md)
+ * [Overriding Dependencies](reference/overriding-dependencies.md)
* [The Manifest Format](reference/manifest.md)
+ * [Cargo Targets](reference/cargo-targets.md)
+ * [Workspaces](reference/workspaces.md)
+ * [Features](reference/features.md)
* [Profiles](reference/profiles.md)
* [Configuration](reference/config.md)
* [Environment Variables](reference/environment-variables.md)
diff --git a/src/doc/src/appendix/glossary.md b/src/doc/src/appendix/glossary.md
index 4bd44c54c3c..d643f593c45 100644
--- a/src/doc/src/appendix/glossary.md
+++ b/src/doc/src/appendix/glossary.md
@@ -135,9 +135,9 @@ The meaning of the term *target* depends on the context:
`thumb`, `mips`, etc.
- `sub` = The CPU sub-architecture, for example `arm` has `v7`, `v7s`,
`v5te`, etc.
- - `vendor` = The vendor, for example `unknown`, `apple`, `pc`, `linux`, etc.
- - `sys` = The system name, for example `linux`, `windows`, etc. `none` is
- typically used for bare-metal without an OS.
+ - `vendor` = The vendor, for example `unknown`, `apple`, `pc`, `nvidia`, etc.
+ - `sys` = The system name, for example `linux`, `windows`, `darwin`, etc.
+ `none` is typically used for bare-metal without an OS.
- `abi` = The ABI, for example `gnu`, `android`, `eabi`, etc.
Some parameters may be omitted. Run `rustc --print target-list` for a list of
@@ -178,21 +178,21 @@ manifest is located.
[Source Replacement]: ../reference/source-replacement.md
[cargo-unstable]: ../reference/unstable.md
[config option]: ../reference/config.md
-[directory layout]: ../reference/manifest.md#the-project-layout
+[directory layout]: ../guide/project-layout.md
[edition guide]: ../../edition-guide/index.html
-[edition-field]: ../reference/manifest.md#the-edition-field-optional
+[edition-field]: ../reference/manifest.md#the-edition-field
[environment variable]: ../reference/environment-variables.md
-[feature]: ../reference/manifest.md#the-features-section
+[feature]: ../reference/features.md
[git dependency]: ../reference/specifying-dependencies.md#specifying-dependencies-from-git-repositories
[git source]: ../reference/source-replacement.md
-[integration-tests]: ../reference/manifest.md#integration-tests
+[integration-tests]: ../reference/cargo-targets.md#integration-tests
[manifest]: ../reference/manifest.md
[path dependency]: ../reference/specifying-dependencies.md#specifying-path-dependencies
-[path overrides]: ../reference/specifying-dependencies.md#overriding-with-local-dependencies
+[path overrides]: ../reference/overriding-dependencies.md#paths-overrides
[pkgid-spec]: ../reference/pkgid-spec.md
[rustdoc-unstable]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.html
[target-feature]: ../../reference/attributes/codegen.html#the-target_feature-attribute
-[targets]: ../reference/manifest.md#configuring-a-target
+[targets]: ../reference/cargo-targets.md#configuring-a-target
[unstable-book]: https://doc.rust-lang.org/nightly/unstable-book/index.html
-[virtual]: ../reference/manifest.md#virtual-manifest
-[workspace]: ../reference/manifest.md#the-workspace-section
+[virtual]: ../reference/workspaces.md
+[workspace]: ../reference/workspaces.md
diff --git a/src/doc/src/faq.md b/src/doc/src/faq.md
index ee006621856..2a58bdaf45a 100644
--- a/src/doc/src/faq.md
+++ b/src/doc/src/faq.md
@@ -178,7 +178,7 @@ and a populated cache of the crates reflected in the lock file. If either of
these components are missing, then they're required for the build to succeed and
must be fetched remotely.
-As of Rust 1.11.0 Cargo understands a new flag, `--frozen`, which is an
+As of Rust 1.11.0, Cargo understands a new flag, `--frozen`, which is an
assertion that it shouldn't touch the network. When passed, Cargo will
immediately return an error if it would otherwise attempt a network request.
The error should include contextual information about why the network request is
@@ -187,7 +187,15 @@ not change the behavior of Cargo*, it simply asserts that Cargo shouldn't touch
the network as a previous command has been run to ensure that network activity
shouldn't be necessary.
+The `--offline` flag was added in Rust 1.36.0. This flag tells Cargo to not
+access the network, and try to proceed with available cached data if possible.
+You can use [`cargo fetch`] in one project to download dependencies before
+going offline, and then use those same dependencies in another project with
+the `--offline` flag (or [configuration value][offline config]).
+
For more information about vendoring, see documentation on [source
replacement][replace].
[replace]: reference/source-replacement.md
+[`cargo fetch`]: commands/cargo-fetch.md
+[offline config]: reference/config.md#netoffline
diff --git a/src/doc/src/guide/build-cache.md b/src/doc/src/guide/build-cache.md
index a84bbdf4b9f..f1722932574 100644
--- a/src/doc/src/guide/build-cache.md
+++ b/src/doc/src/guide/build-cache.md
@@ -1,15 +1,94 @@
## Build cache
-Cargo shares build artifacts among all the packages of a single workspace.
-Today, Cargo does not share build results across different workspaces, but
-a similar result can be achieved by using a third party tool, [sccache].
+Cargo stores the output of a build into the "target" directory. By default,
+this is the directory named `target` in the root of your workspace. To change
+the location, you can set the `CARGO_TARGET_DIR` [environment variable], the
+[`build.target-dir`] config value, or the `--target-dir` command-line flag.
-To setup `sccache`, install it with `cargo install sccache` and set
-`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo.
-If you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to
-`.bashrc`. Alternatively, you can set `build.rustc-wrapper` in the
- [Cargo configuration][config]. Refer to sccache documentation for more
- details.
+The directory layout depends on whether or not you are using the `--target`
+flag to build for a specific platform. If `--target` is not specified, Cargo
+runs in a mode where it builds for the host architecture. The output goes into
+the root of the target directory, separated based on whether or not it is a
+release build:
-[sccache]: https://github.com/mozilla/sccache
+Directory | Description
+----------|------------
+target/debug/ | Contains debug build output.
+target/release/ | Contains release build output (with `--release` flag).
+
+When building for another target with `--target`, the output is placed in a
+directory with the name of the target:
+
+Directory | Example
+----------|--------
+target/<triple>/debug/ | target/thumbv7em-none-eabihf/debug/
+target/<triple>/release/ | target/thumbv7em-none-eabihf/release/
+
+> **Note**: When not using `--target`, this has a consequence that Cargo will
+> share your dependencies with build scripts and proc macros. [`RUSTFLAGS`]
+> will be shared with every `rustc` invocation. With the `--target` flag,
+> build scripts and proc macros are built separately (for the host
+> architecture), and do not share `RUSTFLAGS`.
+
+Within the profile directory (`debug` or `release`), artifacts are placed into
+the following directories:
+
+Directory | Description
+----------|------------
+target/debug/ | Contains the output of the package being built (the `[[bin]]` executables and `[lib]` library targets).
+target/debug/examples/ | Contains examples (`[[example]]` targets).
+
+Some commands place their output in dedicated directories in the top level of
+the `target` directory:
+
+Directory | Description
+----------|------------
+target/doc/ | Contains rustdoc documentation ([`cargo doc`]).
+target/package/ | Contains the output of the [`cargo package`] and [`cargo publish`] commands.
+
+Cargo also creates several other directories and files needed for the build
+process. Their layout is considered internal to Cargo, and is subject to
+change. Some of these directories are:
+
+Directory | Description
+----------|------------
+target/debug/deps/ | Dependencies and other artifacts.
+target/debug/incremental/ | `rustc` [incremental output], a cache used to speed up subsequent builds.
+target/debug/build/ | Output from [build scripts].
+
+### Dep-info files
+
+Next to each compiled artifact is a file called a "dep info" file with a `.d`
+suffix. This file is a Makefile-like syntax that indicates all of the file
+dependencies required to rebuild the artifact. These are intended to be used
+with external build systems so that they can detect if Cargo needs to be
+re-executed. The paths in the file are absolute by default. See the
+[`build.dep-info-basedir`] config option to use relative paths.
+
+```Makefile
+# Example dep-info file found in target/debug/foo.d
+/path/to/myproj/target/debug/foo: /path/to/myproj/src/lib.rs /path/to/myproj/src/main.rs
+```
+
+### Shared cache
+
+A third party tool, [sccache], can be used to share built dependencies across
+different workspaces.
+
+To setup `sccache`, install it with `cargo install sccache` and set
+`RUSTC_WRAPPER` environmental variable to `sccache` before invoking Cargo. If
+you use bash, it makes sense to add `export RUSTC_WRAPPER=sccache` to
+`.bashrc`. Alternatively, you can set [`build.rustc-wrapper`] in the [Cargo
+configuration][config]. Refer to sccache documentation for more details.
+
+[`RUSTFLAGS`]: ../reference/config.md#buildrustflags
+[`build.dep-info-basedir`]: ../reference/config.md#builddep-info-basedir
+[`build.target-dir`]: ../reference/config.md#buildtarget-dir
+[`cargo doc`]: ../commands/cargo-doc.md
+[`cargo package`]: ../commands/cargo-package.md
+[`cargo publish`]: ../commands/cargo-publish.md
+[build scripts]: ../reference/build-scripts.md
[config]: ../reference/config.md
+[environment variable]: ../reference/environment-variables.md
+[incremental output]: ../reference/profiles.md#incremental
+[sccache]: https://github.com/mozilla/sccache
diff --git a/src/doc/src/guide/project-layout.md b/src/doc/src/guide/project-layout.md
index 6c9f4a7719c..4869924c688 100644
--- a/src/doc/src/guide/project-layout.md
+++ b/src/doc/src/guide/project-layout.md
@@ -3,21 +3,34 @@
Cargo uses conventions for file placement to make it easy to dive into a new
Cargo package:
-```
+```text
.
├── Cargo.lock
├── Cargo.toml
-├── benches
-│ └── large-input.rs
-├── examples
-│ └── simple.rs
-├── src
-│ ├── bin
-│ │ └── another_executable.rs
+├── src/
│ ├── lib.rs
-│ └── main.rs
-└── tests
- └── some-integration-tests.rs
+│ ├── main.rs
+│ └── bin/
+│ ├── named-executable.rs
+│ ├── another-executable.rs
+│ └── multi-file-executable/
+│ ├── main.rs
+│ └── some_module.rs
+├── benches/
+│ ├── large-input.rs
+│ └── multi-file-bench/
+│ ├── main.rs
+│ └── bench_module.rs
+├── examples/
+│ ├── simple.rs
+│ └── multi-file-example/
+│ ├── main.rs
+│ └── ex_module.rs
+└── tests/
+ ├── some-integration-tests.rs
+ └── multi-file-test/
+ ├── main.rs
+ └── test_module.rs
```
* `Cargo.toml` and `Cargo.lock` are stored in the root of your package (*package
@@ -25,11 +38,22 @@ Cargo package:
* Source code goes in the `src` directory.
* The default library file is `src/lib.rs`.
* The default executable file is `src/main.rs`.
-* Other executables can be placed in `src/bin/*.rs`.
-* Integration tests go in the `tests` directory (unit tests go in each file
- they're testing).
-* Examples go in the `examples` directory.
+ * Other executables can be placed in `src/bin/`.
* Benchmarks go in the `benches` directory.
+* Examples go in the `examples` directory.
+* Integration tests go in the `tests` directory.
+
+If a binary, example, bench, or integration test consists of multiple source
+files, place a `main.rs` file along with the extra modules within a
+subdirectory of the `src/bin`, `examples`, `benches`, or `tests` directory.
+The name of the executable will be the directory name.
+
+You can learn more about Rust's module system in [the book][book-modules].
+
+See [Configuring a target] for more details on manually configuring targets.
+See [Target auto-discovery] for more information on controlling how Cargo
+automatically infers target names.
-These are explained in more detail in the [manifest
-description](../reference/manifest.md#the-project-layout).
+[book-modules]: ../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html
+[Configuring a target]: ../reference/cargo-targets.md#configuring-a-target
+[Target auto-discovery]: ../reference/cargo-targets.md#target-auto-discovery
diff --git a/src/doc/src/images/profile-selection.svg b/src/doc/src/images/profile-selection.svg
new file mode 100644
index 00000000000..4975383bf76
--- /dev/null
+++ b/src/doc/src/images/profile-selection.svg
@@ -0,0 +1,3 @@
+
+
+
\ No newline at end of file
diff --git a/src/doc/src/index.md b/src/doc/src/index.md
index b33385c4823..17595ff9cd9 100644
--- a/src/doc/src/index.md
+++ b/src/doc/src/index.md
@@ -25,6 +25,10 @@ The reference covers the details of various areas of Cargo.
**[Frequently Asked Questions](faq.md)**
+**Appendicies:**
+* [Glossary](appendix/glossary.md)
+* [Git Authentication](appendix/git-authentication.md)
+
[rust]: https://www.rust-lang.org/
[crates.io]: https://crates.io/
[GitHub]: https://github.com/rust-lang/cargo/tree/master/src/doc
diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md
index 4800e229cc7..3bdbb6254f2 100644
--- a/src/doc/src/reference/build-scripts.md
+++ b/src/doc/src/reference/build-scripts.md
@@ -176,7 +176,7 @@ of `feature=`). Or an arbitrary key/value pair may be used with an `=` symbol
like `cargo:rustc-cfg=my_component="foo"`. The key should be a Rust
identifier, the value should be a string.
-[cargo features]: manifest.md#the-features-section
+[cargo features]: features.md
[conditional compilation]: ../../reference/conditional-compilation.md
[option-cfg]: ../../rustc/command-line-arguments.md#option-cfg
@@ -240,11 +240,14 @@ cross-compiling, so keep that in consideration of the impact on compile time.
When rebuilding a package, Cargo does not necessarily know if the build script
needs to be run again. By default, it takes a conservative approach of always
-re-running the build script if any file within the package is changed. For
-most cases, this is not a good choice, so it is recommended that every build
-script emit at least one of the `rerun-if` instructions (described below). If
-these are emitted, then Cargo will only re-run the script if the given value
-has changed.
+re-running the build script if any file within the package is changed (or the
+list of files controlled by the [`exclude` and `include` fields]). For most
+cases, this is not a good choice, so it is recommended that every build script
+emit at least one of the `rerun-if` instructions (described below). If these
+are emitted, then Cargo will only re-run the script if the given value has
+changed.
+
+[`exclude` and `include` fields]: manifest.md#the-exclude-and-include-fields
#### `cargo:rerun-if-changed=PATH`
diff --git a/src/doc/src/reference/cargo-targets.md b/src/doc/src/reference/cargo-targets.md
new file mode 100644
index 00000000000..4be13c3529f
--- /dev/null
+++ b/src/doc/src/reference/cargo-targets.md
@@ -0,0 +1,372 @@
+## Cargo Targets
+
+Cargo packages consist of *targets* which correspond to source files which can
+be compiled into a crate. Packages can have [library](#library),
+[binary](#binaries), [example](#examples), [test](#tests), and
+[benchmark](#benchmarks) targets. The list of targets can be configured in the
+`Cargo.toml` manifest, often [inferred automatically](#target-auto-discovery)
+by the [directory layout][package layout] of the source files.
+
+See [Configuring a target](#configuring-a-target) below for details on
+configuring the settings for a target.
+
+### Library
+
+The library target defines a "library" that can be used and linked by other
+libraries and executables. The filename defaults to `src/lib.rs`, and the name
+of the library defaults to the name of the package. A package can have only
+one library. The settings for the library can be [customized] in the `[lib]`
+table in `Cargo.toml`.
+
+```toml
+# Example of customizing the library in Cargo.toml.
+[lib]
+crate-type = ["cdylib"]
+bench = false
+```
+
+### Binaries
+
+Binary targets are executables programs that can be run after being compiled.
+The default binary filename is `src/main.rs`, which defaults to the name of
+the package. Additional binaries are stored in the [`src/bin/`
+directory][package layout]. The settings for each binary can be [customized]
+in the `[[bin]]` tables in `Cargo.toml`.
+
+Binaries can use the public API of the package's library. They are also linked
+with the [`[dependencies]`][dependencies] defined in `Cargo.toml`.
+
+You can run individual binaries with the [`cargo run`] command with the `--bin
+` option. [`cargo install`] can be used to copy the executable to a
+common location.
+
+```toml
+# Example of customizing binaries in Cargo.toml.
+[[bin]]
+name = "cool-tool"
+test = false
+bench = false
+
+[[bin]]
+name = "frobnicator"
+required-features = ["frobnicate"]
+```
+
+### Examples
+
+Files located under the [`examples` directory][package layout] are example
+uses of the functionality provided by the library. When compiled, they are
+placed in the [`target/debug/examples` directory][build cache].
+
+Examples can use the public API of the package's library. They are also linked
+with the [`[dependencies]`][dependencies] and
+[`[dev-dependencies]`][dev-dependencies] defined in `Cargo.toml`.
+
+By default, examples are executable binaries (with a `main()` function). You
+can specify the [`crate-type` field](#the-crate-type-field) to make an example
+be compiled as a library:
+
+```toml
+[[example]]
+name = "foo"
+crate-type = ["staticlib"]
+```
+
+You can run individual executable examples with the [`cargo run`] command with
+the `--example ` option. Library examples can be built with
+[`cargo build`] with the `--example ` option. [`cargo install`]
+with the `--example ` option can be used to copy executable
+binaries to a common location. Examples are compiled by [`cargo test`] by
+default to protect them from bit-rotting. Set [the `test`
+field](#the-test-field) to `true` if you have `#[test]` functions in the
+example that you want to run with [`cargo test`].
+
+### Tests
+
+There are two styles of tests within a Cargo project:
+
+* *Unit tests* which are functions marked with the [`#[test]`
+ attribute][test-attribute] located within your library or binaries (or any
+ target enabled with [the `test` field](#the-test-field)). These tests have
+ access to private APIs located within the target they are defined in.
+* *Integration tests* which is a separate executable binary, also containing
+ `#[test]` functions, which is linked with the project's library and has
+ access to its *public* API.
+
+Tests are run with the [`cargo test`] command. By default, Cargo and `rustc`
+use the libtest harness which is responsible for collecting functions
+annotated with the [`#[test]` attribute][test-attribute] and executing them in
+parallel, reporting the success and failure of each test. See [the `harness`
+field](#the-harness-field) if you want to use a different harness or test
+strategy.
+
+#### Integration tests
+
+Files located under the [`tests` directory][package layout] are integration
+tests. When you run [`cargo test`], Cargo will compile each of these files as
+a separate crate, and execute them.
+
+Integration tests can use the public API of the package's library. They are
+also linked with the [`[dependencies]`][dependencies] and
+[`[dev-dependencies]`][dev-dependencies] defined in `Cargo.toml`.
+
+If you want to share code among multiple integration tests, you can place it
+in a separate module such as `tests/common/mod.rs` and then put `mod common;`
+in each test to import it.
+
+Each integration test results in a separate executable binary, and [`cargo
+test`] will run them serially. In some cases this can be inefficient, as it
+can take longer to compile, and may not make full use of multiple CPUs when
+running the tests. If you have a lot of integration tests, you may want to
+consider creating a single integration test, and split the tests into multiple
+modules. The libtest harness will automatically find all of the `#[test]`
+annotated functions and run them in parallel. You can pass module names to
+[`cargo test`] to only run the tests within that module.
+
+### Benchmarks
+
+Benchmarks provide a way to test the performance of your code using the
+[`cargo bench`] command. They follow the same structure as [tests](#tests),
+with each benchmark function annotated with the `#[bench]` attribute.
+Similarly to tests:
+
+* Benchmarks are placed in the [`benches` directory][package layout].
+* Benchmark functions defined in libraries and binaries have access to the
+ *private* API within the target they are defined in. Benchmarks in the
+ `benches` directory may use the *public* API.
+* [The `bench` field](#the-bench-field) can be used to define which targets
+ are benchmarked by default.
+* [The `harness` field](#the-harness-field) can be used to disable the
+ built-in harness.
+
+> **Note**: The [`#[bench]`
+> attribute](../../unstable-book/library-features/test.html) is currently
+> unstable and only available on the [nightly channel]. There are some
+> packages available on [crates.io](https://crates.io/keywords/benchmark) that
+> may help with running benchmarks on the stable channel, such as
+> [Criterion](https://crates.io/crates/criterion).
+
+### Configuring a target
+
+All of the `[lib]`, `[[bin]]`, `[[example]]`, `[[test]]`, and `[[bench]]`
+sections in `Cargo.toml` support similar configuration for specifying how a
+target should be built. The double-bracket sections like `[[bin]]` are
+array-of-table of [TOML](https://github.com/toml-lang/toml#array-of-tables),
+which means you can write more than one `[[bin]]` section to make several
+executables in your crate. You can only specify one library, so `[lib]` is a
+normal TOML table.
+
+The following is an overview of the TOML settings for each target, with each
+field described in detail below.
+
+```toml
+[lib]
+name = "foo" # The name of the target.
+path = "src/lib.rs" # The source file of the target.
+test = true # Is tested by default.
+doctest = true # Documentation examples are tested by default.
+bench = true # Is benchmarked by default.
+doc = true # Is documented by default.
+plugin = false # Used as a compiler plugin (deprecated).
+proc-macro = false # Set to `true` for a proc-macro library.
+harness = true # Use libtest harness.
+edition = "2015" # The edition of the target.
+crate-type = ["lib"] # The crate types to generate.
+required-features = [] # Features required to build this target (N/A for lib).
+```
+
+#### The `name` field
+
+The `name` field specifies the name of the target, which corresponds to the
+filename of the artifact that will be generated. For a library, this is the
+crate name that dependencies will use to reference it.
+
+For the `[lib]` and the default binary (`src/main.rs`), this defaults to the
+name of the package, with any dashes replaced with underscores. For other
+[auto discovered](#target-auto-discovery) targets, it defaults to the
+directory or file name.
+
+This is required for all targets except `[lib]`.
+
+#### The `path` field
+
+The `path` field specifies where the source for the crate is located, relative
+to the `Cargo.toml` file.
+
+If not specified, the [inferred path](#target-auto-discovery) is used based on
+the target name.
+
+#### The `test` field
+
+The `test` field indicates whether or not the target is tested by default by
+[`cargo test`]. The default is `true` for lib, bins, and tests.
+
+> **Note**: Examples are built by [`cargo test`] by default to ensure they
+> continue to compile, but they are not *tested* by default. Setting `test =
+> true` for an example will also build it as a test and run any
+> [`#[test]`][test-attribute] functions defined in the example.
+
+#### The `doctest` field
+
+The `doctest` field indicates whether or not [documentation examples] are
+tested by default by [`cargo test`]. This is only relevant for libraries, it
+has no effect on other sections. The default is `true` for the library.
+
+#### The `bench` field
+
+The `bench` field indicates whether or not the target is benchmarked by
+default by [`cargo bench`]. The default is `true` for lib, bins, and
+benchmarks.
+
+#### The `doc` field
+
+The `doc` field indicates whether or not the target is included in the
+documentation generated by [`cargo doc`] by default. The default is `true` for
+libraries and binaries.
+
+> **Note**: The binary will be skipped if its name is the same as the lib
+> target.
+
+#### The `plugin` field
+
+This field is used for `rustc` plugins, which are being deprecated.
+
+#### The `proc-macro` field
+
+The `proc-macro` field indicates that the library is a [procedural macro]
+([reference][proc-macro-reference]). This is only valid for the `[lib]`
+target.
+
+#### The `harness` field
+
+The `harness` field indicates that the [`--test` flag] will be passed to
+`rustc` which will automatically include the libtest library which is the
+driver for collecting and running tests marked with the [`#[test]`
+attribute][test-attribute] or benchmarks with the `#[bench]` attribute. The
+default is `true` for all targets.
+
+If set to `false`, then you are responsible for defining a `main()` function
+to run tests and benchmarks.
+
+Tests have the [`cfg(test)` conditional expression][cfg-test] enabled whether
+or not the harness is enabled.
+
+#### The `edition` field
+
+The `edition` field defines the [Rust edition] the target will use. If not
+specified, it defaults to the [`edition` field][package-edition] for the
+`[package]`. This field should usually not be set, and is only intended for
+advanced scenarios such as incrementally transitioning a large package to a
+new edition.
+
+#### The `crate-type` field
+
+The `crate-type` field defines the [crate types] that will be generated by the
+target. It is an array of strings, allowing you to specify multiple crate
+types for a single target. This can only be specified for libraries and
+examples. Binaries, tests, and benchmarks are always the "bin" crate type. The
+defaults are:
+
+Target | Crate Type
+-------|-----------
+Normal library | `"lib"`
+Proc-macro library | `"proc-macro"`
+Example | `"bin"`
+
+The available options are `bin`, `lib`, `rlib`, `dylib`, `cdylib`,
+`staticlib`, and `proc-macro`. You can read more about the different crate
+types in the [Rust Reference Manual][crate types].
+
+#### The `required-features` field
+
+The `required-features` field specifies which [features] the target needs in
+order to be built. If any of the required features are not enabled, the
+target will be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`,
+`[[test]]`, and `[[example]]` sections, it has no effect on `[lib]`.
+
+```toml
+[features]
+# ...
+postgres = []
+sqlite = []
+tools = []
+
+[[bin]]
+name = "my-pg-tool"
+required-features = ["postgres", "tools"]
+```
+
+
+### Target auto-discovery
+
+By default, Cargo automatically determines the targets to build based on the
+[layout of the files][package layout] on the filesystem. The target
+configuration tables, such as `[lib]`, `[[bin]]`, `[[test]]`, `[[bench]]`, or
+`[[example]]`, can be used to add additional targets that don't follow the
+standard directory layout.
+
+The automatic target discovery can be disabled so that only manually
+configured targets will be built. Setting the keys `autobins`, `autoexamples`,
+`autotests`, or `autobenches` to `false` in the `[package]` section will
+disable auto-discovery of the corresponding target type.
+
+```toml
+[package]
+# ...
+autobins = false
+autoexamples = false
+autotests = false
+autobenches = false
+```
+
+Disabling automatic discovery should only be needed for specialized
+situations. For example, if you have a library where you want a *module* named
+`bin`, this would present a problem because Cargo would usually attempt to
+compile anything in the `bin` directory as an executable. Here is a sample
+layout of this scenario:
+
+```
+├── Cargo.toml
+└── src
+ ├── lib.rs
+ └── bin
+ └── mod.rs
+```
+
+To prevent Cargo from inferring `src/bin/mod.rs` as an executable, set
+`autobins = false` in `Cargo.toml` to disable auto-discovery:
+
+```toml
+[package]
+# …
+autobins = false
+```
+
+> **Note**: For packages with the 2015 edition, the default for auto-discovery
+> is `false` if at least one target is manually defined in `Cargo.toml`.
+> Beginning with the 2018 edition, the default is always `true`.
+
+
+[Build cache]: ../guide/build-cache.md
+[Rust Edition]: ../../edition-guide/index.html
+[`--test` flag]: ../../rustc/command-line-arguments.html#option-test
+[`cargo bench`]: ../commands/cargo-bench.md
+[`cargo build`]: ../commands/cargo-build.md
+[`cargo doc`]: ../commands/cargo-doc.md
+[`cargo install`]: ../commands/cargo-install.md
+[`cargo run`]: ../commands/cargo-run.md
+[`cargo test`]: ../commands/cargo-test.md
+[cfg-test]: ../../reference/conditional-compilation.html#test
+[crate types]: ../../reference/linkage.html
+[crates.io]: https://crates.io/
+[customized]: #configuring-a-target
+[dependencies]: specifying-dependencies.md
+[dev-dependencies]: specifying-dependencies.md#development-dependencies
+[documentation examples]: ../../rustdoc/documentation-tests.html
+[features]: features.md
+[nightly channel]: ../../book/appendix-07-nightly-rust.html
+[package layout]: ../guide/project-layout.md
+[package-edition]: manifest.md#the-edition-field
+[proc-macro-reference]: ../../reference/procedural-macros.html
+[procedural macro]: ../../book/ch19-06-macros.html
+[test-attribute]: ../../reference/attributes/testing.html#the-test-attribute
diff --git a/src/doc/src/reference/config.md b/src/doc/src/reference/config.md
index e580e9158b5..943f6a0e81d 100644
--- a/src/doc/src/reference/config.md
+++ b/src/doc/src/reference/config.md
@@ -207,8 +207,8 @@ the `` part can be any target triple like
* Environment: not supported
An array of paths to local packages which are to be used as overrides for
-dependencies. For more information see the [Specifying Dependencies
-guide](specifying-dependencies.md#overriding-with-local-dependencies).
+dependencies. For more information see the [Overriding Dependencies
+guide](overriding-dependencies.md#paths-overrides).
#### `[alias]`
* Type: string or array of strings
@@ -348,14 +348,10 @@ overrides the config setting.
* Default: none
* Environment: `CARGO_BUILD_DEP_INFO_BASEDIR`
-Strips the given path prefix from dep info file paths.
-
-Cargo saves a "dep info" file with a `.d` suffix which is a Makefile-like
-syntax that indicates all of the file dependencies required to rebuild the
-artifact. These are intended to be used with external build systems so that
-they can detect if Cargo needs to be re-executed. The paths in the file are
-absolute by default. This config setting can be set to strip the given prefix
-from all of the paths for tools that require relative paths.
+Strips the given path prefix from [dep
+info](../guide/build-cache.md#dep-info-files) file paths. This config setting
+is intended to convert absolute paths to relative paths for tools that require
+relative paths.
The setting itself is a config-relative path. So, for example, a value of
`"."` would strip all paths starting with the parent directory of the `.cargo`
diff --git a/src/doc/src/reference/external-tools.md b/src/doc/src/reference/external-tools.md
index 5611b3f9658..9aaf85dc8b3 100644
--- a/src/doc/src/reference/external-tools.md
+++ b/src/doc/src/reference/external-tools.md
@@ -241,5 +241,11 @@ Cargo. Alternatively, it can link to `cargo` crate as a library, but this
approach has drawbacks:
* Cargo as a library is unstable: the API may change without deprecation
-
* versions of the linked Cargo library may be different from the Cargo binary
+
+Instead, it is encouraged to use the CLI interface to drive Cargo. The [`cargo
+metadata`] command can be used to obtain information about the current project
+(the [`cargo_metadata`] crate provides a Rust interface to this command).
+
+[`cargo metadata`]: ../commands/cargo-metadata.md
+[`cargo_metadata`]: https://crates.io/crates/cargo_metadata
diff --git a/src/doc/src/reference/features.md b/src/doc/src/reference/features.md
new file mode 100644
index 00000000000..611058e7fa2
--- /dev/null
+++ b/src/doc/src/reference/features.md
@@ -0,0 +1,134 @@
+## Features
+
+Cargo supports features to allow expression of:
+
+* conditional compilation options (usable through `cfg` attributes);
+* optional dependencies, which enhance a package, but are not required; and
+* clusters of optional dependencies, such as `postgres-all`, that would include the
+ `postgres` package, the `postgres-macros` package, and possibly other packages
+ (such as development-time mocking libraries, debugging tools, etc.).
+
+A feature of a package is either an optional dependency, or a set of other
+features.
+
+### The `[features]` section
+
+Features are defined in the `[features]` table of `Cargo.toml`. The format for
+specifying features is:
+
+```toml
+[package]
+name = "awesome"
+
+[features]
+# The default set of optional packages. Most people will want to use these
+# packages, but they are strictly optional. Note that `session` is not a package
+# but rather another feature listed in this manifest.
+default = ["jquery", "uglifier", "session"]
+
+# A feature with no dependencies is used mainly for conditional compilation,
+# like `#[cfg(feature = "go-faster")]`.
+go-faster = []
+
+# The `secure-password` feature depends on the bcrypt package. This aliasing
+# will allow people to talk about the feature in a higher-level way and allow
+# this package to add more requirements to the feature in the future.
+secure-password = ["bcrypt"]
+
+# Features can be used to reexport features of other packages. The `session`
+# feature of package `awesome` will ensure that the `session` feature of the
+# package `cookie` is also enabled.
+session = ["cookie/session"]
+
+[dependencies]
+# These packages are mandatory and form the core of this package’s distribution.
+cookie = "1.2.0"
+oauth = "1.1.0"
+route-recognizer = "=2.1.0"
+
+# A list of all of the optional dependencies, some of which are included in the
+# above `features`. They can be opted into by apps.
+jquery = { version = "1.0.2", optional = true }
+uglifier = { version = "1.5.3", optional = true }
+bcrypt = { version = "*", optional = true }
+civet = { version = "*", optional = true }
+```
+
+To use the package `awesome`:
+
+```toml
+[dependencies.awesome]
+version = "1.3.5"
+default-features = false # do not include the default features, and optionally
+ # cherry-pick individual features
+features = ["secure-password", "civet"]
+```
+
+### Rules
+
+The usage of features is subject to a few rules:
+
+* Feature names must not conflict with other package names in the manifest. This
+ is because they are opted into via `features = [...]`, which only has a single
+ namespace.
+* With the exception of the `default` feature, all features are opt-in. To opt
+ out of the default feature, use `default-features = false` and cherry-pick
+ individual features.
+* Feature groups are not allowed to cyclically depend on one another.
+* Dev-dependencies cannot be optional.
+* Features groups can only reference optional dependencies.
+* When a feature is selected, Cargo will call `rustc` with `--cfg
+ feature="${feature_name}"`. If a feature group is included, it and all of its
+ individual features will be included. This can be tested in code via
+ `#[cfg(feature = "foo")]`.
+
+Note that it is explicitly allowed for features to not actually activate any
+optional dependencies. This allows packages to internally enable/disable
+features without requiring a new dependency.
+
+> **Note**: [crates.io] requires feature names to only contain ASCII letters,
+> digits, `_`, or `-`.
+
+### Usage in end products
+
+One major use-case for this feature is specifying optional features in
+end-products. For example, the Servo package may want to include optional
+features that people can enable or disable when they build it.
+
+In that case, Servo will describe features in its `Cargo.toml` and they can be
+enabled using command-line flags:
+
+```console
+$ cargo build --release --features "shumway pdf"
+```
+
+Default features could be excluded using `--no-default-features`.
+
+### Usage in packages
+
+In most cases, the concept of *optional dependency* in a library is best
+expressed as a separate package that the top-level application depends on.
+
+However, high-level packages, like Iron or Piston, may want the ability to
+curate a number of packages for easy installation. The current Cargo system
+allows them to curate a number of mandatory dependencies into a single package
+for easy installation.
+
+In some cases, packages may want to provide additional curation for optional
+dependencies:
+
+* grouping a number of low-level optional dependencies together into a single
+ high-level feature;
+* specifying packages that are recommended (or suggested) to be included by
+ users of the package; and
+* including a feature (like `secure-password` in the motivating example) that
+ will only work if an optional dependency is available, and would be difficult
+ to implement as a separate package (for example, it may be overly difficult to
+ design an IO package to be completely decoupled from OpenSSL, with opt-in via
+ the inclusion of a separate package).
+
+In almost all cases, it is an antipattern to use these features outside of
+high-level packages that are designed for curation. If a feature is optional, it
+can almost certainly be expressed as a separate package.
+
+[crates.io]: https://crates.io/
diff --git a/src/doc/src/reference/index.md b/src/doc/src/reference/index.md
index a9bf76c8537..dd41258fd73 100644
--- a/src/doc/src/reference/index.md
+++ b/src/doc/src/reference/index.md
@@ -3,12 +3,19 @@
The reference covers the details of various areas of Cargo.
* [Specifying Dependencies](specifying-dependencies.md)
+ * [Overriding Dependencies](overriding-dependencies.md)
* [The Manifest Format](manifest.md)
+ * [Cargo Targets](cargo-targets.md)
+* [Workspaces](workspaces.md)
+* [Features](features.md)
+* [Profiles](profiles.md)
* [Configuration](config.md)
* [Environment Variables](environment-variables.md)
* [Build Scripts](build-scripts.md)
+ * [Build Script Examples](build-script-examples.md)
* [Publishing on crates.io](publishing.md)
* [Package ID Specifications](pkgid-spec.md)
* [Source Replacement](source-replacement.md)
* [External Tools](external-tools.md)
+* [Registries](registries.md)
* [Unstable Features](unstable.md)
diff --git a/src/doc/src/reference/manifest.md b/src/doc/src/reference/manifest.md
index 9842329f5e5..5dfb54e37c7 100644
--- a/src/doc/src/reference/manifest.md
+++ b/src/doc/src/reference/manifest.md
@@ -1,8 +1,54 @@
## The Manifest Format
The `Cargo.toml` file for each package is called its *manifest*. Every manifest
-file consists of one or more sections.
-
+file consists of the following sections:
+
+* [`cargo-features`](unstable.md) — Unstable, nightly-only features.
+* [`[package]`](#the-package-section) — Defines a package.
+ * [`name`](#the-name-field) — The name of the package.
+ * [`version`](#the-version-field) — The version of the package.
+ * [`authors`](#the-authors-field) — The authors of the package.
+ * [`edition`](#the-edition-field) — The Rust edition.
+ * [`description`](#the-description-field) — A description of the package.
+ * [`documentation`](#the-documentation-field) — URL of the package documentation.
+ * [`readme`](#the-readme-field) — Path to the package's README file.
+ * [`homepage`](#the-homepage-field) — URL of the package homepage.
+ * [`repository`](#the-repository-field) — URL of the package source repository.
+ * [`license`](#the-license-and-license-file-fields) — The package license.
+ * [`license-file`](#the-license-and-license-file-fields) — Path to the text of the license.
+ * [`keywords`](#the-keywords-field) — Keywords for the package.
+ * [`categories`](#the-categories-field) — Categories of the package.
+ * [`workspace`](#the-workspace-field) — Path to the workspace for the package.
+ * [`build`](#the-build-field) — Path to the package build script.
+ * [`links`](#the-links-field) — Name of the native library the package links with.
+ * [`exclude`](#the-exclude-and-include-fields) — Files to exclude when publishing.
+ * [`include`](#the-exclude-and-include-fields) — Files to include when publishing.
+ * [`publish`](#the-publish-field) — Can be used to prevent publishing the package.
+ * [`metadata`](#the-metadata-table) — Extra settings for external tools.
+ * [`default-run`](#the-default-run-field) — The default binary to run by [`cargo run`].
+ * [`autobins`](cargo-targets.md#target-auto-discovery) — Disables binary auto discovery.
+ * [`autoexamples`](cargo-targets.md#target-auto-discovery) — Disables example auto discovery.
+ * [`autotests`](cargo-targets.md#target-auto-discovery) — Disables test auto discovery.
+ * [`autobenches`](cargo-targets.md#target-auto-discovery) — Disables bench auto discovery.
+* Target tables: (see [configuration](cargo-targets.md#configuring-a-target) for settings)
+ * [`[lib]`](cargo-targets.md#library) — Library target settings.
+ * [`[[bin]]`](cargo-targets.md#binaries) — Binary target settings.
+ * [`[[example]]`](cargo-targets.md#examples) — Example target settings.
+ * [`[[test]]`](cargo-targets.md#tests) — Test target settings.
+ * [`[[bench]]`](cargo-targets.md#benchmarks) — Benchmark target settings.
+* Dependency tables:
+ * [`[dependencies]`](specifying-dependencies.md) — Package library dependencies.
+ * [`[dev-dependencies]`](specifying-dependencies.md#development-dependencies) — Dependencies for examples, tests, and benchmarks.
+ * [`[build-dependencies]`](specifying-dependencies.md#build-dependencies) — Dependencies for build scripts.
+ * [`[target]`](specifying-dependencies.md#platform-specific-dependencies) — Platform-specific dependencies.
+* [`[badges]`](#the-badges-section) — Badges to display on [crates.io].
+* [`[features]`](features.md) — Conditional compilation features.
+* [`[patch]`](overriding-dependencies.md#the-patch-section) — Override dependencies.
+* [`[replace]`](overriding-dependencies.md#the-replace-section) — Override dependencies (deprecated).
+* [`[profile]`](profiles.md) — Compiler settings and optimizations.
+* [`[workspace]`](workspaces.md) — The workspace definition.
+
+
### The `[package]` section
The first section in a `Cargo.toml` is `[package]`.
@@ -14,16 +60,21 @@ version = "0.1.0" # the current version, obeying semver
authors = ["Alice ", "Bob "]
```
+The only fields required by Cargo are [`name`](#the-name-field) and
+[`version`](#the-version-field). If publishing to a registry, the registry may
+require additional fields. See the notes below and [the publishing
+chapter][publishing] for requirements for publishing to [crates.io].
+
#### The `name` field
The package name is an identifier used to refer to the package. It is used
when listed as a dependency in another package, and as the default name of
inferred lib and bin targets.
-The name must not be empty, use only [alphanumeric] characters or `-` or `_`.
+The name must use only [alphanumeric] characters or `-` or `_`, and cannot be empty.
Note that [`cargo new`] and [`cargo init`] impose some additional restrictions on
the package name, such as enforcing that it is a valid Rust identifier and not
-a keyword. [crates.io][cratesio] imposes even more restrictions, such as
+a keyword. [crates.io] imposes even more restrictions, such as
enforcing only ASCII characters, not a reserved name, not a special Windows
name such as "nul", is not too long, etc.
@@ -44,18 +95,20 @@ Versioning](https://semver.org/), so make sure you follow some basic rules:
traits, fields, types, functions, methods or anything else.
* Use version numbers with three numeric parts such as 1.0.0 rather than 1.0.
-#### The `authors` field (optional)
+#### The `authors` field
The `authors` field lists people or organizations that are considered the
"authors" of the package. The exact meaning is open to interpretation — it may
list the original or primary authors, current maintainers, or owners of the
package. These names will be listed on the crate's page on
-[crates.io][cratesio]. An optional email address may be included within angled
+[crates.io]. An optional email address may be included within angled
brackets at the end of each author.
-#### The `edition` field (optional)
+> **Note**: [crates.io] requires at least one author to be listed.
+
+#### The `edition` field
-You can opt in to a specific Rust Edition for your package with the
+You can opt in to a specific [Rust Edition] for your package with the
`edition` key in `Cargo.toml`. If you don't specify the edition, it will
default to 2015.
@@ -71,12 +124,167 @@ latest edition. Setting the `edition` key in `[package]` will affect all
targets/crates in the package, including test suites, benchmarks, binaries,
examples, etc.
+#### The `description` field
+
+The description is a short blurb about the package. [crates.io] will display
+this with your package. This should be plain text (not Markdown).
+
+```toml
+[package]
+# ...
+description = "A short description of my package"
+```
+
+> **Note**: [crates.io] requires the `description` to be set.
+
+#### The `documentation` field
+
+The `documentation` field specifies a URL to a website hosting the crate's
+documentation. If no URL is specified in the manifest file, [crates.io] will
+automatically link your crate to the corresponding [docs.rs] page.
+
+```toml
+[package]
+# ...
+documentation = "https://docs.rs/bitflags"
+```
+
+> **Note**: [crates.io] may not show certain sites if they are known to not be
+> hosting documentation and are possibly of malicious intent e.g., ad tracking
+> networks. At this time, the site `rust-ci.org` is not allowed.
+
+#### The `readme` field
+
+The `readme` field should be the path to a file in the package root (relative
+to this `Cargo.toml`) that contains general information about the package.
+This file will be transferred to the registry when you publish. [crates.io]
+will interpret it as Markdown and render it on the crate's page.
+
+```toml
+[package]
+# ...
+readme = "README.md"
+```
+
+#### The `homepage` field
+
+The `homepage` field should be a URL to a site that is the home page for your
+package.
+
+```toml
+[package]
+# ...
+homepage = "https://serde.rs/"
+```
+
+#### The `repository` field
+
+The `repository` field should be a URL to the source repository for your
+package.
+
+```toml
+[package]
+# ...
+repository = "https://github.com/rust-lang/cargo/"
+```
+
+#### The `license` and `license-file` fields
+
+The `license` field contains the name of the software license that the package
+is released under. The `license-file` field contains the path to a file
+containing the text of the license (relative to this `Cargo.toml`).
+
+[crates.io] interprets the `license` field as an [SPDX 2.1 license
+expression][spdx-2.1-license-expressions]. The name must be a known license
+from the [SPDX license list 3.6][spdx-license-list-3.6]. Parentheses are not
+currently supported. See the [SPDX site] for more information.
+
+SPDX license expressions support AND and OR operators to combine multiple
+licenses.[^slash]
+
+```toml
+[package]
+# ...
+license = "MIT OR Apache-2.0"
+```
+
+Using `OR` indicates the user may choose either license. Using `AND` indicates
+the user must comply with both licenses simultaneously. The `WITH` operator
+indicates a license with a special exception. Some examples:
+
+* `MIT OR Apache-2.0`
+* `LGPL-2.1 AND MIT AND BSD-2-Clause`
+* `GPL-2.0+ WITH Bison-exception-2.2`
+
+If a package is using a nonstandard license, then the `license-file` field may
+be specified in lieu of the `license` field.
+
+```toml
+[package]
+# ...
+license-file = "LICENSE.txt"
+```
+
+> **Note**: [crates.io] requires either `license` or `license-file` to be set.
+
+[^slash]: Previously multiple licenses could be separated with a `/`, but that
+usage is deprecated.
+
+#### The `keywords` field
+
+The `keywords` field is an array of strings that describe this package. This
+can help when searching for the package on a registry, and you may choose any
+words that would help someone find this crate.
+
+```toml
+[package]
+# ...
+keywords = ["gamedev", "graphics"]
+```
+
+> **Note**: [crates.io] has a maximum of 5 keywords. Each keyword must be
+> ASCII text, start with a letter, and only contain letters, numbers, `_` or
+> `-`, and have at most 20 characters.
+
+#### The `categories` field
+
+The `categories` field is an array of strings of the categories this package
+belongs to.
+
+```toml
+categories = ["command-line-utilities", "development-tools::cargo-plugins"]
+```
+
+> **Note**: [crates.io] has a maximum of 5 categories. Each category should
+> match one of the strings available at , and
+> must match exactly.
+
+#### The `workspace` field
+
+The `workspace` field can be used to configure the workspace that this package
+will be a member of. If not specified this will be inferred as the first
+Cargo.toml with `[workspace]` upwards in the filesystem. Setting this is
+useful if the member is not inside a subdirectory of the workspace root.
+
+```toml
+[package]
+# ...
+workspace = "path/to/workspace/root"
+```
+
+This field cannot be specified if the manifest already has a `[workspace]`
+table defined. That is, a crate cannot both be a root crate in a workspace
+(contain `[workspace]`) and also be a member crate of another workspace
+(contain `package.workspace`).
+
+For more information, see the [workspaces chapter](workspaces.md).
+
-#### The `build` field (optional)
+#### The `build` field
-This field specifies a file in the package root which is a [build script] for
-building native code. More information can be found in the [build script
-guide][build script].
+The `build` field specifies a file in the package root which is a [build
+script] for building native code. More information can be found in the [build
+script guide][build script].
[build script]: build-scripts.md
@@ -91,10 +299,10 @@ The default is `"build.rs"`, which loads the script from a file named
specify a path to a different file or `build = false` to disable automatic
detection of the build script.
-#### The `links` field (optional)
+#### The `links` field
-This field specifies the name of a native library that is being linked to.
-More information can be found in the [`links`][links] section of the build
+The `links` field specifies the name of a native library that is being linked
+to. More information can be found in the [`links`][links] section of the build
script guide.
[links]: build-scripts.md#the-links-manifest-key
@@ -105,26 +313,7 @@ script guide.
links = "foo"
```
-#### The `documentation` field (optional)
-
-This field specifies a URL to a website hosting the crate's documentation.
-If no URL is specified in the manifest file, [crates.io][cratesio] will
-automatically link your crate to the corresponding [docs.rs][docsrs] page.
-
-Documentation links from specific hosts are blacklisted. Hosts are added
-to the blacklist if they are known to not be hosting documentation and are
-possibly of malicious intent e.g., ad tracking networks. URLs from the
-following hosts are blacklisted:
-
-* rust-ci.org
-
-Documentation URLs from blacklisted hosts will not appear on crates.io, and
-may be replaced by docs.rs links.
-
-[docsrs]: https://docs.rs/
-[cratesio]: https://crates.io/
-
-#### The `exclude` and `include` fields (optional)
+#### The `exclude` and `include` fields
You can explicitly specify that a set of file patterns should be ignored or
included for the purposes of packaging. The patterns specified in the
@@ -186,7 +375,7 @@ if any of those files change.
[gitignore]: https://git-scm.com/docs/gitignore
-#### The `publish` field (optional)
+#### The `publish` field
The `publish` field can be used to prevent a package from being published to a
package registry (like *crates.io*) by mistake, for instance to keep a package
@@ -207,93 +396,39 @@ allowed to be published to.
publish = ["some-registry-name"]
```
-#### The `workspace` field (optional)
+#### The `metadata` table
-The `workspace` field can be used to configure the workspace that this package
-will be a member of. If not specified this will be inferred as the first
-Cargo.toml with `[workspace]` upwards in the filesystem.
-
-```toml
-[package]
-# ...
-workspace = "path/to/workspace/root"
-```
-
-For more information, see the documentation for the workspace table below.
-
-#### The `license` and `license-file` fields (optional)
-
-The `license` field can be set to an [SPDX 2.1 license
-expression][spdx-2.1-license-expressions] for the package. Currently crates.io
-will validate the license provided against a whitelist of known license and
-exception identifiers from the [SPDX license list 3.6][spdx-license-list-3.6].
-Parentheses are not currently supported.
-
-Previously multiple licenses could be separated with a `/`, but that usage is
-deprecated. Instead, use a license expression with AND and OR operators to get
-more explicit semantics.
+Cargo by default will warn about unused keys in `Cargo.toml` to assist in
+detecting typos and such. The `package.metadata` table, however, is completely
+ignored by Cargo and will not be warned about. This section can be used for
+tools which would like to store package configuration in `Cargo.toml`. For
+example:
```toml
[package]
+name = "..."
# ...
-license = "MIT OR Apache-2.0"
-```
-
-If a package is using a nonstandard license, then the `license-file` field may
-be specified in lieu of the `license` field. It must point to a file relative to
-this manifest (similar to the `readme` field).
-```toml
-[package]
-# ...
-license-file = "..."
+# Metadata used when generating an Android APK, for example.
+[package.metadata.android]
+package-name = "my-awesome-android-app"
+assets = "path/to/static"
```
-#### Package metadata
+#### The `default-run` field
-There are a number of optional metadata fields also accepted under the
-`[package]` section:
+The `default-run` field in the `[package]` section of the manifest can be used
+to specify a default binary picked by [`cargo run`]. For example, when there is
+both `src/bin/a.rs` and `src/bin/b.rs`:
```toml
[package]
-# ...
-
-# A short blurb about the package. This is not rendered in any format when
-# uploaded to crates.io (aka this is not markdown).
-description = "..."
-
-# These URLs point to more information about the package. These are
-# intended to be webviews of the relevant data, not necessarily compatible
-# with VCS tools and the like.
-documentation = "..."
-homepage = "..."
-repository = "..."
-
-# This points to a file under the package root (relative to this `Cargo.toml`).
-# The contents of this file are stored and indexed in the registry.
-# crates.io will render this file and place the result on the crate's page.
-readme = "..."
-
-# This is a list of up to five keywords that describe this crate. Keywords
-# are searchable on crates.io, and you may choose any words that would
-# help someone find this crate.
-keywords = ["...", "..."]
-
-# This is a list of up to five categories where this crate would fit.
-# Categories are a fixed list available at crates.io/category_slugs, and
-# they must match exactly.
-categories = ["...", "..."]
+default-run = "a"
```
-The [crates.io](https://crates.io) registry will render the description, display
-the license, link to the three URLs and categorize by the keywords. These keys
-provide useful information to users of the registry and also influence the
-search ranking of a crate. It is highly discouraged to omit everything in a
-published crate.
-
### The `[badges]` section
-crates.io can display various badges for build status, test coverage, etc. for
+[crates.io] can display various badges for build status, test coverage, etc. for
each crate. All badges are optional.
- The badges pertaining to build status that are currently available are
@@ -370,36 +505,6 @@ is-it-maintained-open-issues = { repository = "..." }
maintenance = { status = "..." }
```
-#### The `metadata` table (optional)
-
-Cargo by default will warn about unused keys in `Cargo.toml` to assist in
-detecting typos and such. The `package.metadata` table, however, is completely
-ignored by Cargo and will not be warned about. This section can be used for
-tools which would like to store package configuration in `Cargo.toml`. For
-example:
-
-```toml
-[package]
-name = "..."
-# ...
-
-# Metadata used when generating an Android APK, for example.
-[package.metadata.android]
-package-name = "my-awesome-android-app"
-assets = "path/to/static"
-```
-
-#### The `default-run` field
-
-The `default-run` field in the `[package]` section of the manifest can be used
-to specify a default binary picked by [`cargo run`]. For example, when there is
-both `src/bin/a.rs` and `src/bin/b.rs`:
-
-```toml
-[package]
-default-run = "a"
-```
-
### Dependency sections
See the [specifying dependencies page](specifying-dependencies.md) for
@@ -412,550 +517,46 @@ The `[profile]` tables provide a way to customize compiler settings such as
optimizations and debug settings. See [the Profiles chapter](profiles.md) for
more detail.
-### The `[features]` section
-
-Cargo supports features to allow expression of:
-
-* conditional compilation options (usable through `cfg` attributes);
-* optional dependencies, which enhance a package, but are not required; and
-* clusters of optional dependencies, such as `postgres-all`, that would include the
- `postgres` package, the `postgres-macros` package, and possibly other packages
- (such as development-time mocking libraries, debugging tools, etc.).
-
-A feature of a package is either an optional dependency, or a set of other
-features. The format for specifying features is:
-
-```toml
-[package]
-name = "awesome"
-
-[features]
-# The default set of optional packages. Most people will want to use these
-# packages, but they are strictly optional. Note that `session` is not a package
-# but rather another feature listed in this manifest.
-default = ["jquery", "uglifier", "session"]
-
-# A feature with no dependencies is used mainly for conditional compilation,
-# like `#[cfg(feature = "go-faster")]`.
-go-faster = []
-
-# The `secure-password` feature depends on the bcrypt package. This aliasing
-# will allow people to talk about the feature in a higher-level way and allow
-# this package to add more requirements to the feature in the future.
-secure-password = ["bcrypt"]
-
-# Features can be used to reexport features of other packages. The `session`
-# feature of package `awesome` will ensure that the `session` feature of the
-# package `cookie` is also enabled.
-session = ["cookie/session"]
-
-[dependencies]
-# These packages are mandatory and form the core of this package’s distribution.
-cookie = "1.2.0"
-oauth = "1.1.0"
-route-recognizer = "=2.1.0"
-
-# A list of all of the optional dependencies, some of which are included in the
-# above `features`. They can be opted into by apps.
-jquery = { version = "1.0.2", optional = true }
-uglifier = { version = "1.5.3", optional = true }
-bcrypt = { version = "*", optional = true }
-civet = { version = "*", optional = true }
-```
-
-To use the package `awesome`:
-
-```toml
-[dependencies.awesome]
-version = "1.3.5"
-default-features = false # do not include the default features, and optionally
- # cherry-pick individual features
-features = ["secure-password", "civet"]
-```
-
-#### Rules
-
-The usage of features is subject to a few rules:
-
-* Feature names must not conflict with other package names in the manifest. This
- is because they are opted into via `features = [...]`, which only has a single
- namespace.
-* With the exception of the `default` feature, all features are opt-in. To opt
- out of the default feature, use `default-features = false` and cherry-pick
- individual features.
-* Feature groups are not allowed to cyclically depend on one another.
-* Dev-dependencies cannot be optional.
-* Features groups can only reference optional dependencies.
-* When a feature is selected, Cargo will call `rustc` with `--cfg
- feature="${feature_name}"`. If a feature group is included, it and all of its
- individual features will be included. This can be tested in code via
- `#[cfg(feature = "foo")]`.
-
-Note that it is explicitly allowed for features to not actually activate any
-optional dependencies. This allows packages to internally enable/disable
-features without requiring a new dependency.
-
-#### Usage in end products
-
-One major use-case for this feature is specifying optional features in
-end-products. For example, the Servo package may want to include optional
-features that people can enable or disable when they build it.
-
-In that case, Servo will describe features in its `Cargo.toml` and they can be
-enabled using command-line flags:
-
-```console
-$ cargo build --release --features "shumway pdf"
-```
-
-Default features could be excluded using `--no-default-features`.
-
-#### Usage in packages
-
-In most cases, the concept of *optional dependency* in a library is best
-expressed as a separate package that the top-level application depends on.
-
-However, high-level packages, like Iron or Piston, may want the ability to
-curate a number of packages for easy installation. The current Cargo system
-allows them to curate a number of mandatory dependencies into a single package
-for easy installation.
-
-In some cases, packages may want to provide additional curation for optional
-dependencies:
-
-* grouping a number of low-level optional dependencies together into a single
- high-level feature;
-* specifying packages that are recommended (or suggested) to be included by
- users of the package; and
-* including a feature (like `secure-password` in the motivating example) that
- will only work if an optional dependency is available, and would be difficult
- to implement as a separate package (for example, it may be overly difficult to
- design an IO package to be completely decoupled from OpenSSL, with opt-in via
- the inclusion of a separate package).
-
-In almost all cases, it is an antipattern to use these features outside of
-high-level packages that are designed for curation. If a feature is optional, it
-can almost certainly be expressed as a separate package.
-
-### The `[workspace]` section
-
-Packages can define a workspace which is a set of crates that will all share the
-same `Cargo.lock` and output directory. The `[workspace]` table can be defined
-as:
-
-```toml
-[workspace]
-
-# Optional key, inferred from path dependencies if not present.
-# Additional non-path dependencies that should be included must be given here.
-# In particular, for a virtual manifest, all members have to be listed.
-members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
-
-# Optional key, empty if not present.
-exclude = ["path1", "path/to/dir2"]
-```
-
-Workspaces were added to Cargo as part of [RFC 1525] and have a number of
-properties:
-
-* A workspace can contain multiple crates where one of them is the *root crate*.
-* The *root crate*'s `Cargo.toml` contains the `[workspace]` table, but is not
- required to have other configuration.
-* Whenever any crate in the workspace is compiled, output is placed in the
- *workspace root* (i.e., next to the *root crate*'s `Cargo.toml`).
-* The lock file for all crates in the workspace resides in the *workspace root*.
-* The `[patch]`, `[replace]` and `[profile.*]` sections in `Cargo.toml`
- are only recognized
- in the *root crate*'s manifest, and ignored in member crates' manifests.
-
-[RFC 1525]: https://github.com/rust-lang/rfcs/blob/master/text/1525-cargo-workspace.md
-
-The *root crate* of a workspace, indicated by the presence of `[workspace]` in
-its manifest, is responsible for defining the entire workspace. All `path`
-dependencies residing in the workspace directory become members. You can add
-additional packages to the workspace by listing them in the `members` key. Note
-that members of the workspaces listed explicitly will also have their path
-dependencies included in the workspace. Sometimes a package may have a lot of
-workspace members and it can be onerous to keep up to date. The `members` list
-can also use [globs][globs] to match multiple paths. Finally, the `exclude`
-key can be used to blacklist paths from being included in a workspace. This can
-be useful if some path dependencies aren't desired to be in the workspace at
-all.
-
-The `package.workspace` manifest key (described above) is used in member crates
-to point at a workspace's root crate. If this key is omitted then it is inferred
-to be the first crate whose manifest contains `[workspace]` upwards in the
-filesystem.
-
-A crate may either specify `package.workspace` or specify `[workspace]`. That
-is, a crate cannot both be a root crate in a workspace (contain `[workspace]`)
-and also be a member crate of another workspace (contain `package.workspace`).
-
-Most of the time workspaces will not need to be dealt with as [`cargo new`] and
-[`cargo init`] will handle workspace configuration automatically.
-
-[globs]: https://docs.rs/glob/0.2.11/glob/struct.Pattern.html
-
-#### Virtual Manifest
-
-In workspace manifests, if the `package` table is present, the workspace root
-crate will be treated as a normal package, as well as a workspace. If the
-`package` table is not present in a workspace manifest, it is called a *virtual
-manifest*.
-
-#### Package selection
-
-In a workspace, package-related cargo commands like [`cargo build`] apply to
-packages selected by `-p` / `--package` or `--workspace` command-line parameters.
-When neither is specified, the optional `default-members` configuration is used:
-
-```toml
-[workspace]
-members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
-default-members = ["path/to/member2", "path/to/member3/foo"]
-```
-
-When specified, `default-members` must expand to a subset of `members`.
-
-When `default-members` is not specified, the default is the root manifest
-if it is a package, or every member manifest (as if `--workspace` were specified
-on the command-line) for virtual workspaces.
-
-### The project layout
-
-If your package is an executable, name the main source file `src/main.rs`. If it
-is a library, name the main source file `src/lib.rs`.
-
-Cargo will also treat any files located in `src/bin/*.rs` as executables. If your
-executable consists of more than just one source file, you might also use a directory
-inside `src/bin` containing a `main.rs` file which will be treated as an executable
-with a name of the parent directory.
-
-Your package can optionally contain folders named `examples`, `tests`, and
-`benches`, which Cargo will treat as containing examples,
-integration tests, and benchmarks respectively. Analogous to `bin` targets, they
-may be composed of single files or directories with a `main.rs` file.
-
-```
-▾ src/ # directory containing source files
- lib.rs # the main entry point for libraries and packages
- main.rs # the main entry point for packages producing executables
- ▾ bin/ # (optional) directory containing additional executables
- *.rs
- ▾ */ # (optional) directories containing multi-file executables
- main.rs
-▾ examples/ # (optional) examples
- *.rs
- ▾ */ # (optional) directories containing multi-file examples
- main.rs
-▾ tests/ # (optional) integration tests
- *.rs
- ▾ */ # (optional) directories containing multi-file tests
- main.rs
-▾ benches/ # (optional) benchmarks
- *.rs
- ▾ */ # (optional) directories containing multi-file benchmarks
- main.rs
-```
-
-To structure your code after you've created the files and folders for your
-package, you should remember to use Rust's module system, which you can read
-about in [the
-book](../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html).
-
-See [Configuring a target](#configuring-a-target) below for more details on
-manually configuring target settings. See [Target
-auto-discovery](#target-auto-discovery) below for more information on
-controlling how Cargo automatically infers targets.
-
-### Examples
-
-Files located under `examples` are example uses of the functionality provided by
-the library. When compiled, they are placed in the `target/examples` directory.
-
-They can compile either as executables (with a `main()` function) or libraries
-and pull in the library by using `extern crate `. They are
-compiled when you run your tests to protect them from bitrotting.
-
-You can run individual executable examples with the command `cargo run --example
-`.
-Specify `crate-type` to make an example be compiled as a library (additional
-information about crate types is available in
-[The Rust Reference](../../reference/linkage.html)):
-```toml
-[[example]]
-name = "foo"
-crate-type = ["staticlib"]
-```
-
-You can build individual library examples with the command `cargo build
---example `.
-
-### Tests
-
-When you run [`cargo test`], Cargo will:
-
-* compile and run your library’s unit tests, which are in the files reachable
- from `lib.rs` (naturally, any sections marked with `#[cfg(test)]` will be
- considered at this stage);
-* compile and run your library’s documentation tests, which are embedded inside
- of documentation blocks;
-* compile and run your library’s [integration tests](#integration-tests); and
-* compile your library’s examples.
-
-#### Integration tests
-
-Each file in `tests/*.rs` is an integration test. When you run [`cargo test`],
-Cargo will compile each of these files as a separate crate. The crate can link
-to your library by using `extern crate `, like any other code that
-depends on it.
-
-Cargo will not automatically compile files inside subdirectories of `tests`, but
-an integration test can import modules from these directories as usual. For
-example, if you want several integration tests to share some code, you can put
-the shared code in `tests/common/mod.rs` and then put `mod common;` in each of
-the test files.
-
-### Configuring a target
-
-All of the `[[bin]]`, `[lib]`, `[[bench]]`, `[[test]]`, and `[[example]]`
-sections support similar configuration for specifying how a target should be
-built. The double-bracket sections like `[[bin]]` are array-of-table of
-[TOML](https://github.com/toml-lang/toml#array-of-tables), which means you can
-write more than one `[[bin]]` section to make several executables in your crate.
-
-The example below uses `[lib]`, but it also applies to all other sections
-as well. All values listed are the defaults for that option unless otherwise
-specified.
-
-```toml
-[package]
-# ...
-
-[lib]
-# The name of a target is the name of the library that will be generated. This
-# is defaulted to the name of the package, with any dashes replaced
-# with underscores. (Rust `extern crate` declarations reference this name;
-# therefore the value must be a valid Rust identifier to be usable.)
-name = "foo"
-
-# This field points at where the crate is located, relative to the `Cargo.toml`.
-path = "src/lib.rs"
-
-# A flag for enabling unit tests for this target. This is used by `cargo test`.
-test = true
-
-# A flag for enabling documentation tests for this target. This is only relevant
-# for libraries, it has no effect on other sections. This is used by
-# `cargo test`.
-doctest = true
-
-# A flag for enabling benchmarks for this target. This is used by `cargo bench`.
-bench = true
-
-# A flag for enabling documentation of this target. This is used by `cargo doc`.
-doc = true
-
-# If the target is meant to be a compiler plugin, this field must be set to true
-# for Cargo to correctly compile it and make it available for all dependencies.
-plugin = false
-
-# If the target is meant to be a "macros 1.1" procedural macro, this field must
-# be set to true.
-proc-macro = false
-
-# If set to false, `cargo test` will omit the `--test` flag to rustc, which
-# stops it from generating a test harness. This is useful when the binary being
-# built manages the test runner itself.
-harness = true
-
-# If set then a target can be configured to use a different edition than the
-# `[package]` is configured to use, perhaps only compiling a library with the
-# 2018 edition or only compiling one unit test with the 2015 edition. By default
-# all targets are compiled with the edition specified in `[package]`.
-edition = '2015'
-
-# Here's an example of a TOML "array of tables" section, in this case specifying
-# a binary target name and path.
-[[bin]]
-name = "my-cool-binary"
-path = "src/my-cool-binary.rs"
-```
-
-#### Target auto-discovery
-
-By default, Cargo automatically determines the targets to build based on the
-[layout of the files](#the-project-layout) on the filesystem. The target
-configuration tables, such as `[lib]`, `[[bin]]`, `[[test]]`, `[[bench]]`, or
-`[[example]]`, can be used to add additional targets that don't follow the
-standard directory layout.
-
-The automatic target discovery can be disabled so that only manually
-configured targets will be built. Setting the keys `autobins`, `autoexamples`,
-`autotests`, or `autobenches` to `false` in the `[package]` section will
-disable auto-discovery of the corresponding target type.
-
-Disabling automatic discovery should only be needed for specialized
-situations. For example, if you have a library where you want a *module* named
-`bin`, this would present a problem because Cargo would usually attempt to
-compile anything in the `bin` directory as an executable. Here is a sample
-layout of this scenario:
-
-```
-├── Cargo.toml
-└── src
- ├── lib.rs
- └── bin
- └── mod.rs
-```
-
-To prevent Cargo from inferring `src/bin/mod.rs` as an executable, set
-`autobins = false` in `Cargo.toml` to disable auto-discovery:
-
-```toml
-[package]
-# …
-autobins = false
-```
-
-> **Note**: For packages with the 2015 edition, the default for auto-discovery
-> is `false` if at least one target is manually defined in `Cargo.toml`.
-> Beginning with the 2018 edition, the default is always `true`.
-
-#### The `required-features` field (optional)
-
-The `required-features` field specifies which features the target needs in order
-to be built. If any of the required features are not selected, the target will
-be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, `[[test]]`,
-and `[[example]]` sections, it has no effect on `[lib]`.
-
-```toml
-[features]
-# ...
-postgres = []
-sqlite = []
-tools = []
-
-[[bin]]
-# ...
-required-features = ["postgres", "tools"]
-```
-
-#### Building dynamic or static libraries
-
-If your package produces a library, you can specify which kind of library to
-build by explicitly listing the library in your `Cargo.toml`:
-
-```toml
-# ...
-
-[lib]
-name = "..."
-crate-type = ["dylib"] # could be `staticlib` as well
-```
-
-The available options are `dylib`, `rlib`, `staticlib`, `cdylib`, and
-`proc-macro`.
-
-You can read more about the different crate types in the
-[Rust Reference Manual](../../reference/linkage.html)
-
-### The `[patch]` Section
-
-This section of Cargo.toml can be used to [override dependencies][replace] with
-other copies. The syntax is similar to the `[dependencies]` section:
-
-```toml
-[patch.crates-io]
-foo = { git = 'https://github.com/example/foo' }
-bar = { path = 'my/local/bar' }
-
-[dependencies.baz]
-git = 'https://github.com/example/baz'
-
-[patch.'https://github.com/example/baz']
-baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }
-```
-
-The `[patch]` table is made of dependency-like sub-tables. Each key after
-`[patch]` is a URL of the source that is being patched, or the name of a
-registry. The name `crates-io` may be used to override the default registry
-[crates.io]. The first `[patch]` in the example above demonstrates overriding
-[crates.io], and the second `[patch]` demonstrates overriding a git source.
-
-Each entry in these tables is a normal dependency specification, the same as
-found in the `[dependencies]` section of the manifest. The dependencies listed
-in the `[patch]` section are resolved and used to patch the source at the
-URL specified. The above manifest snippet patches the `crates-io` source (e.g.
-crates.io itself) with the `foo` crate and `bar` crate. It also
-patches the `https://github.com/example/baz` source with a `my-branch` that
-comes from elsewhere.
-
-Sources can be patched with versions of crates that do not exist, and they can
-also be patched with versions of crates that already exist. If a source is
-patched with a crate version that already exists in the source, then the
-source's original crate is replaced.
-
-More information about overriding dependencies can be found in the [overriding
-dependencies][replace] section of the documentation and [RFC 1969] for the
-technical specification of this feature.
-
-[RFC 1969]: https://github.com/rust-lang/rfcs/pull/1969
-[crates.io]: https://crates.io/
-[replace]: specifying-dependencies.md#overriding-dependencies
-
-#### Using `[patch]` with multiple versions
-
-You can patch in multiple versions of the same crate with the `package` key used
-to rename dependencies. For example let's say that the `serde` crate has a
-bugfix that we'd like to use to its 1.\* series but we'd also like to prototype
-using a 2.0.0 version of serde we have in our git repository. To configure this
-we'd do:
-
-```toml
-[patch.crates-io]
-serde = { git = 'https://github.com/serde-rs/serde' }
-serde2 = { git = 'https://github.com/example/serde', package = 'serde', branch = 'v2' }
-```
-
-The first `serde = ...` directive indicates that serde 1.\* should be used from
-the git repository (pulling in the bugfix we need) and the second `serde2 = ...`
-directive indicates that the `serde` package should also be pulled from the `v2`
-branch of `https://github.com/example/serde`. We're assuming here that
-`Cargo.toml` on that branch mentions version 2.0.0.
-
-Note that when using the `package` key the `serde2` identifier here is actually
-ignored. We simply need a unique name which doesn't conflict with other patched
-crates.
-
-### The `[replace]` Section
-
-This section of Cargo.toml can be used to [override dependencies][replace] with
-other copies. The syntax is similar to the `[dependencies]` section:
-
-```toml
-[replace]
-"foo:0.1.0" = { git = 'https://github.com/example/foo' }
-"bar:1.0.2" = { path = 'my/local/bar' }
-```
-
-Each key in the `[replace]` table is a [package ID
-specification](pkgid-spec.md), which allows arbitrarily choosing a node in the
-dependency graph to override. The value of each key is the same as the
-`[dependencies]` syntax for specifying dependencies, except that you can't
-specify features. Note that when a crate is overridden the copy it's overridden
-with must have both the same name and version, but it can come from a different
-source (e.g., git or a local path).
-
-More information about overriding dependencies can be found in the [overriding
-dependencies][replace] section of the documentation.
-
-[`cargo build`]: ../commands/cargo-build.md
[`cargo init`]: ../commands/cargo-init.md
[`cargo new`]: ../commands/cargo-new.md
[`cargo run`]: ../commands/cargo-run.md
-[`cargo test`]: ../commands/cargo-test.md
+[crates.io]: https://crates.io/
+[docs.rs]: https://docs.rs/
+[publishing]: publishing.md
+[Rust Edition]: ../../edition-guide/index.html
[spdx-2.1-license-expressions]: https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60
[spdx-license-list-3.6]: https://github.com/spdx/license-list-data/tree/v3.6
+[SPDX site]: https://spdx.org/license-list
+
+
diff --git a/src/doc/src/reference/overriding-dependencies.md b/src/doc/src/reference/overriding-dependencies.md
new file mode 100644
index 00000000000..fc5308d07a3
--- /dev/null
+++ b/src/doc/src/reference/overriding-dependencies.md
@@ -0,0 +1,349 @@
+## Overriding Dependencies
+
+The desire to override a dependency can arise through a number of scenarios.
+Most of them, however, boil down to the ability to work with a crate before
+it's been published to [crates.io]. For example:
+
+* A crate you're working on is also used in a much larger application you're
+ working on, and you'd like to test a bug fix to the library inside of the
+ larger application.
+* An upstream crate you don't work on has a new feature or a bug fix on the
+ master branch of its git repository which you'd like to test out.
+* You're about to publish a new major version of your crate, but you'd like to
+ do integration testing across an entire package to ensure the new major
+ version works.
+* You've submitted a fix to an upstream crate for a bug you found, but you'd
+ like to immediately have your application start depending on the fixed
+ version of the crate to avoid blocking on the bug fix getting merged.
+
+These scenarios can be solved with the [`[patch]` manifest
+section](#the-patch-section).
+
+This chapter walks through a few different use cases, and includes details
+on the different ways to override a dependency.
+
+* Example use cases
+ * [Testing a bugfix](#testing-a-bugfix)
+ * [Working with an unpublished minor version](#working-with-an-unpublished-minor-version)
+ * [Overriding repository URL](#overriding-repository-url)
+ * [Prepublishing a breaking change](#prepublishing-a-breaking-change)
+ * [Using `[patch]` with multiple versions](#using-patch-with-multiple-versions)
+* Reference
+ * [The `[patch]` section](#the-patch-section)
+ * [The `[replace]` section](#the-replace-section)
+ * [`paths` overrides](#paths-overrides)
+
+> **Note**: See also specifying a dependency with [multiple locations], which
+> can be used to override the source for a single dependency declaration in a
+> local package.
+
+### Testing a bugfix
+
+Let's say you're working with the [`uuid` crate] but while you're working on it
+you discover a bug. You are, however, quite enterprising so you decide to also
+try to fix the bug! Originally your manifest will look like:
+
+[`uuid` crate]: https://crates.io/crates/uuid
+
+```toml
+[package]
+name = "my-library"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+uuid = "1.0"
+```
+
+First thing we'll do is to clone the [`uuid` repository][uuid-repository]
+locally via:
+
+```console
+$ git clone https://github.com/uuid-rs/uuid
+```
+
+Next we'll edit the manifest of `my-library` to contain:
+
+```toml
+[patch.crates-io]
+uuid = { path = "../path/to/uuid" }
+```
+
+Here we declare that we're *patching* the source `crates-io` with a new
+dependency. This will effectively add the local checked out version of `uuid` to
+the crates.io registry for our local package.
+
+Next up we need to ensure that our lock file is updated to use this new version
+of `uuid` so our package uses the locally checked out copy instead of one from
+crates.io. The way `[patch]` works is that it'll load the dependency at
+`../path/to/uuid` and then whenever crates.io is queried for versions of `uuid`
+it'll *also* return the local version.
+
+This means that the version number of the local checkout is significant and will
+affect whether the patch is used. Our manifest declared `uuid = "1.0"` which
+means we'll only resolve to `>= 1.0.0, < 2.0.0`, and Cargo's greedy resolution
+algorithm also means that we'll resolve to the maximum version within that
+range. Typically this doesn't matter as the version of the git repository will
+already be greater or match the maximum version published on crates.io, but it's
+important to keep this in mind!
+
+In any case, typically all you need to do now is:
+
+```console
+$ cargo build
+ Compiling uuid v1.0.0 (.../uuid)
+ Compiling my-library v0.1.0 (.../my-library)
+ Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs
+```
+
+And that's it! You're now building with the local version of `uuid` (note the
+path in parentheses in the build output). If you don't see the local path version getting
+built then you may need to run `cargo update -p uuid --precise $version` where
+`$version` is the version of the locally checked out copy of `uuid`.
+
+Once you've fixed the bug you originally found the next thing you'll want to do
+is to likely submit that as a pull request to the `uuid` crate itself. Once
+you've done this then you can also update the `[patch]` section. The listing
+inside of `[patch]` is just like the `[dependencies]` section, so once your pull
+request is merged you could change your `path` dependency to:
+
+```toml
+[patch.crates-io]
+uuid = { git = 'https://github.com/uuid-rs/uuid' }
+```
+
+[uuid-repository]: https://github.com/uuid-rs/uuid
+
+### Working with an unpublished minor version
+
+Let's now shift gears a bit from bug fixes to adding features. While working on
+`my-library` you discover that a whole new feature is needed in the `uuid`
+crate. You've implemented this feature, tested it locally above with `[patch]`,
+and submitted a pull request. Let's go over how you continue to use and test it
+before it's actually published.
+
+Let's also say that the current version of `uuid` on crates.io is `1.0.0`, but
+since then the master branch of the git repository has updated to `1.0.1`. This
+branch includes your new feature you submitted previously. To use this
+repository we'll edit our `Cargo.toml` to look like
+
+```toml
+[package]
+name = "my-library"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+uuid = "1.0.1"
+
+[patch.crates-io]
+uuid = { git = 'https://github.com/uuid-rs/uuid' }
+```
+
+Note that our local dependency on `uuid` has been updated to `1.0.1` as it's
+what we'll actually require once the crate is published. This version doesn't
+exist on crates.io, though, so we provide it with the `[patch]` section of the
+manifest.
+
+Now when our library is built it'll fetch `uuid` from the git repository and
+resolve to 1.0.1 inside the repository instead of trying to download a version
+from crates.io. Once 1.0.1 is published on crates.io the `[patch]` section can
+be deleted.
+
+It's also worth noting that `[patch]` applies *transitively*. Let's say you use
+`my-library` in a larger package, such as:
+
+```toml
+[package]
+name = "my-binary"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+my-library = { git = 'https://example.com/git/my-library' }
+uuid = "1.0"
+
+[patch.crates-io]
+uuid = { git = 'https://github.com/uuid-rs/uuid' }
+```
+
+Remember that `[patch]` is applicable *transitively* but can only be defined at
+the *top level* so we consumers of `my-library` have to repeat the `[patch]` section
+if necessary. Here, though, the new `uuid` crate applies to *both* our dependency on
+`uuid` and the `my-library -> uuid` dependency. The `uuid` crate will be resolved to
+one version for this entire crate graph, 1.0.1, and it'll be pulled from the git
+repository.
+
+#### Overriding repository URL
+
+In case the dependency you want to override isn't loaded from `crates.io`,
+you'll have to change a bit how you use `[patch]`. For example, if the
+dependency is a git dependency, you can override it to a local path with:
+
+```toml
+[patch."https://github.com/your/repository"]
+my-library = { path = "../my-library/path" }
+```
+
+And that's it!
+
+### Prepublishing a breaking change
+
+Let's take a look at working with a new major version of a crate, typically
+accompanied with breaking changes. Sticking with our previous crates, this
+means that we're going to be creating version 2.0.0 of the `uuid` crate. After
+we've submitted all changes upstream we can update our manifest for
+`my-library` to look like:
+
+```toml
+[dependencies]
+uuid = "2.0"
+
+[patch.crates-io]
+uuid = { git = "https://github.com/uuid-rs/uuid", branch = "2.0.0" }
+```
+
+And that's it! Like with the previous example the 2.0.0 version doesn't actually
+exist on crates.io but we can still put it in through a git dependency through
+the usage of the `[patch]` section. As a thought exercise let's take another
+look at the `my-binary` manifest from above again as well:
+
+```toml
+[package]
+name = "my-binary"
+version = "0.1.0"
+authors = ["..."]
+
+[dependencies]
+my-library = { git = 'https://example.com/git/my-library' }
+uuid = "1.0"
+
+[patch.crates-io]
+uuid = { git = 'https://github.com/uuid-rs/uuid', branch = '2.0.0' }
+```
+
+Note that this will actually resolve to two versions of the `uuid` crate. The
+`my-binary` crate will continue to use the 1.x.y series of the `uuid` crate but
+the `my-library` crate will use the `2.0.0` version of `uuid`. This will allow you
+to gradually roll out breaking changes to a crate through a dependency graph
+without being force to update everything all at once.
+
+### Using `[patch]` with multiple versions
+
+You can patch in multiple versions of the same crate with the `package` key
+used to rename dependencies. For example let's say that the `serde` crate has
+a bugfix that we'd like to use to its `1.*` series but we'd also like to
+prototype using a `2.0.0` version of serde we have in our git repository. To
+configure this we'd do:
+
+```toml
+[patch.crates-io]
+serde = { git = 'https://github.com/serde-rs/serde' }
+serde2 = { git = 'https://github.com/example/serde', package = 'serde', branch = 'v2' }
+```
+
+The first `serde = ...` directive indicates that serde `1.*` should be used
+from the git repository (pulling in the bugfix we need) and the second `serde2
+= ...` directive indicates that the `serde` package should also be pulled from
+the `v2` branch of `https://github.com/example/serde`. We're assuming here
+that `Cargo.toml` on that branch mentions version `2.0.0`.
+
+Note that when using the `package` key the `serde2` identifier here is actually
+ignored. We simply need a unique name which doesn't conflict with other patched
+crates.
+
+### The `[patch]` section
+
+The `[patch]` section of `Cargo.toml` can be used to override dependencies
+with other copies. The syntax is similar to the
+[`[dependencies]`][dependencies] section:
+
+```toml
+[patch.crates-io]
+foo = { git = 'https://github.com/example/foo' }
+bar = { path = 'my/local/bar' }
+
+[dependencies.baz]
+git = 'https://github.com/example/baz'
+
+[patch.'https://github.com/example/baz']
+baz = { git = 'https://github.com/example/patched-baz', branch = 'my-branch' }
+```
+
+The `[patch]` table is made of dependency-like sub-tables. Each key after
+`[patch]` is a URL of the source that is being patched, or the name of a
+registry. The name `crates-io` may be used to override the default registry
+[crates.io]. The first `[patch]` in the example above demonstrates overriding
+[crates.io], and the second `[patch]` demonstrates overriding a git source.
+
+Each entry in these tables is a normal dependency specification, the same as
+found in the `[dependencies]` section of the manifest. The dependencies listed
+in the `[patch]` section are resolved and used to patch the source at the
+URL specified. The above manifest snippet patches the `crates-io` source (e.g.
+crates.io itself) with the `foo` crate and `bar` crate. It also
+patches the `https://github.com/example/baz` source with a `my-branch` that
+comes from elsewhere.
+
+Sources can be patched with versions of crates that do not exist, and they can
+also be patched with versions of crates that already exist. If a source is
+patched with a crate version that already exists in the source, then the
+source's original crate is replaced.
+
+### The `[replace]` section
+
+> **Note**: `[replace]` is deprecated. You should use the
+> [`[patch]`](#the-patch-section) table instead.
+
+This section of Cargo.toml can be used to override dependencies with other
+copies. The syntax is similar to the `[dependencies]` section:
+
+```toml
+[replace]
+"foo:0.1.0" = { git = 'https://github.com/example/foo' }
+"bar:1.0.2" = { path = 'my/local/bar' }
+```
+
+Each key in the `[replace]` table is a [package ID
+specification](pkgid-spec.md), which allows arbitrarily choosing a node in the
+dependency graph to override (the 3-part version number is required). The
+value of each key is the same as the `[dependencies]` syntax for specifying
+dependencies, except that you can't specify features. Note that when a crate
+is overridden the copy it's overridden with must have both the same name and
+version, but it can come from a different source (e.g., git or a local path).
+
+### `paths` overrides
+
+Sometimes you're only temporarily working on a crate and you don't want to have
+to modify `Cargo.toml` like with the `[patch]` section above. For this use
+case Cargo offers a much more limited version of overrides called **path
+overrides**.
+
+Path overrides are specified through [`.cargo/config`](config.md) instead of
+`Cargo.toml`. Inside of `.cargo/config` you'll specify a key called `paths`:
+
+```toml
+paths = ["/path/to/uuid"]
+```
+
+This array should be filled with directories that contain a `Cargo.toml`. In
+this instance, we’re just adding `uuid`, so it will be the only one that’s
+overridden. This path can be either absolute or relative to the directory that
+contains the `.cargo` folder.
+
+Path overrides are more restricted than the `[patch]` section, however, in
+that they cannot change the structure of the dependency graph. When a
+path replacement is used then the previous set of dependencies
+must all match exactly to the new `Cargo.toml` specification. For example this
+means that path overrides cannot be used to test out adding a dependency to a
+crate, instead `[patch]` must be used in that situation. As a result usage of a
+path override is typically isolated to quick bug fixes rather than larger
+changes.
+
+Note: using a local configuration to override paths will only work for crates
+that have been published to [crates.io]. You cannot use this feature to tell
+Cargo how to find local unpublished crates.
+
+
+[crates.io]: https://crates.io/
+[multiple locations]: specifying-dependencies.md#multiple-locations
+[dependencies]: specifying-dependencies.md
diff --git a/src/doc/src/reference/profiles.md b/src/doc/src/reference/profiles.md
index 88f01800b64..818bd59b3fa 100644
--- a/src/doc/src/reference/profiles.md
+++ b/src/doc/src/reference/profiles.md
@@ -304,6 +304,9 @@ profile. However, when building an integration test target, the library target
is built with the `dev` profile and linked into the integration test
executable.
+
+
+
[`cargo bench`]: ../commands/cargo-bench.md
[`cargo build`]: ../commands/cargo-build.md
[`cargo check`]: ../commands/cargo-check.md
diff --git a/src/doc/src/reference/publishing.md b/src/doc/src/reference/publishing.md
index eea28e9038c..88e6f888fde 100644
--- a/src/doc/src/reference/publishing.md
+++ b/src/doc/src/reference/publishing.md
@@ -30,19 +30,19 @@ immediately.
Keep in mind that crate names on [crates.io] are allocated on a first-come-first-
serve basis. Once a crate name is taken, it cannot be used for another crate.
-Check out the [metadata you can
-specify](manifest.md#package-metadata) in `Cargo.toml` to ensure
-your crate can be discovered more easily! Before publishing, make sure you have
-filled out the following fields:
-
-- `authors`
-- `license` or `license-file`
-- `description`
-- `homepage`
-- `documentation`
-- `repository`
-
-It would also be a good idea to include some `keywords` and `categories`,
+Check out the [metadata you can specify](manifest.md) in `Cargo.toml` to
+ensure your crate can be discovered more easily! Before publishing, make sure
+you have filled out the following fields:
+
+- [`authors`]
+- [`license` or `license-file`]
+- [`description`]
+- [`homepage`]
+- [`documentation`]
+- [`repository`]
+- [`readme`]
+
+It would also be a good idea to include some [`keywords`] and [`categories`],
though they are not required.
If you are publishing a library, you may also want to consult the [Rust API
@@ -83,8 +83,7 @@ $ cargo package --list
Cargo will automatically ignore files ignored by your version control system
when packaging, but if you want to specify an extra set of files to ignore you
-can use the [`exclude`
-key](manifest.md#the-exclude-and-include-fields-optional) in the
+can use the [`exclude` key](manifest.md#the-exclude-and-include-fields) in the
manifest:
```toml
@@ -241,9 +240,17 @@ the “Grant Access” button next to its name:
[RFC 1105]: https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md
[Rust API Guidelines]: https://rust-lang-nursery.github.io/api-guidelines/
+[`authors`]: manifest.md#the-authors-field
[`cargo login`]: ../commands/cargo-login.md
[`cargo package`]: ../commands/cargo-package.md
[`cargo publish`]: ../commands/cargo-publish.md
+[`categories`]: manifest.md#the-categories-field
+[`description`]: manifest.md#the-description-field
+[`documentation`]: manifest.md#the-documentation-field
+[`homepage`]: manifest.md#the-homepage-field
+[`keywords`]: manifest.md#the-keywords-field
+[`license` or `license-file`]: manifest.md#the-license-and-license-file-fields
+[`readme`]: manifest.md#the-readme-field
+[`repository`]: manifest.md#the-repository-field
[crates.io]: https://crates.io/
[oauth-scopes]: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/
-
diff --git a/src/doc/src/reference/source-replacement.md b/src/doc/src/reference/source-replacement.md
index 49f048ecba1..5f5ca237807 100644
--- a/src/doc/src/reference/source-replacement.md
+++ b/src/doc/src/reference/source-replacement.md
@@ -1,7 +1,7 @@
## Source Replacement
This document is about replacing the crate index. You can read about overriding
-dependencies in the [overriding dependencies][overriding] section of this
+dependencies in the [overriding dependencies] section of this
documentation.
A *source* is a provider that contains crates that may be included as
@@ -22,11 +22,12 @@ 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][replace-section], and
-private registry support is described in [Registries][registries].
+dependencies through the usage of [the `[patch]` key][overriding
+dependencies], and private registry support is described in [the Registries
+chapter][registries].
[replace-section]: manifest.md#the-replace-section
-[overriding]: specifying-dependencies.md#overriding-dependencies
+[overriding dependencies]: overriding-dependencies.md
[registries]: registries.md
### Configuration
diff --git a/src/doc/src/reference/specifying-dependencies.md b/src/doc/src/reference/specifying-dependencies.md
index aa2881df00b..324857821f3 100644
--- a/src/doc/src/reference/specifying-dependencies.md
+++ b/src/doc/src/reference/specifying-dependencies.md
@@ -83,6 +83,8 @@ positioned.
1.2.* := >=1.2.0, <1.3.0
```
+> **Note**: [crates.io] does not allow bare `*` versions.
+
### Comparison requirements
**Comparison requirements** allow manually specifying a version range or an
@@ -114,6 +116,9 @@ to the name of the registry to use.
some-crate = { version = "1.0", registry = "my-registry" }
```
+> **Note**: [crates.io] does not allow packages to be published with
+> dependencies on other registries.
+
[registries documentation]: registries.md
### Specifying dependencies from `git` repositories
@@ -144,6 +149,10 @@ rand = { git = "https://github.com/rust-lang-nursery/rand", branch = "next" }
See [Git Authentication] for help with git authentication for private repos.
+> **Note**: [crates.io] does not allow packages to be published with `git`
+> dependencies (`git` [dev-dependencies] are ignored). See the [Multiple
+> locations](#multiple-locations) section for a fallback alternative.
+
[Git Authentication]: ../appendix/git-authentication.md
### Specifying path dependencies
@@ -175,7 +184,7 @@ And that’s it! The next `cargo build` will automatically build `hello_utils` a
all of its own dependencies, and others can also start using the crate as well.
However, crates that use dependencies specified with only a path are not
permitted on [crates.io]. If we wanted to publish our `hello_world` crate, we
-would need to publish a version of `hello_utils` to [crates.io](https://crates.io)
+would need to publish a version of `hello_utils` to [crates.io]
and specify its version in the dependencies line as well:
```toml
@@ -183,266 +192,39 @@ and specify its version in the dependencies line as well:
hello_utils = { path = "hello_utils", version = "0.1.0" }
```
-### Overriding dependencies
-
-There are a number of methods in Cargo to support overriding dependencies and
-otherwise controlling the dependency graph. These options are typically, though,
-only available at the workspace level and aren't propagated through
-dependencies. In other words, "applications" have the ability to override
-dependencies but "libraries" do not.
-
-The desire to override a dependency or otherwise alter some dependencies can
-arise through a number of scenarios. Most of them, however, boil down to the
-ability to work with a crate before it's been published to crates.io. For
-example:
-
-* A crate you're working on is also used in a much larger application you're
- working on, and you'd like to test a bug fix to the library inside of the
- larger application.
-* An upstream crate you don't work on has a new feature or a bug fix on the
- master branch of its git repository which you'd like to test out.
-* You're about to publish a new major version of your crate, but you'd like to
- do integration testing across an entire package to ensure the new major
- version works.
-* You've submitted a fix to an upstream crate for a bug you found, but you'd
- like to immediately have your application start depending on the fixed version
- of the crate to avoid blocking on the bug fix getting merged.
-
-These scenarios are currently all solved with the [`[patch]` manifest
-section][patch-section]. Historically some of these scenarios have been solved
-with [the `[replace]` section][replace-section], but we'll document the `[patch]`
-section here.
-
-[patch-section]: manifest.md#the-patch-section
-[replace-section]: manifest.md#the-replace-section
-
-### Testing a bugfix
-
-Let's say you're working with the [`uuid` crate] but while you're working on it
-you discover a bug. You are, however, quite enterprising so you decide to also
-try to fix the bug! Originally your manifest will look like:
-
-[`uuid` crate]: https://crates.io/crates/uuid
-
-```toml
-[package]
-name = "my-library"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-uuid = "1.0"
-```
-
-First thing we'll do is to clone the [`uuid` repository][uuid-repository]
-locally via:
-
-```console
-$ git clone https://github.com/rust-lang-nursery/uuid
-```
-
-Next we'll edit the manifest of `my-library` to contain:
-
-```toml
-[patch.crates-io]
-uuid = { path = "../path/to/uuid" }
-```
-
-Here we declare that we're *patching* the source `crates-io` with a new
-dependency. This will effectively add the local checked out version of `uuid` to
-the crates.io registry for our local package.
-
-Next up we need to ensure that our lock file is updated to use this new version
-of `uuid` so our package uses the locally checked out copy instead of one from
-crates.io. The way `[patch]` works is that it'll load the dependency at
-`../path/to/uuid` and then whenever crates.io is queried for versions of `uuid`
-it'll *also* return the local version.
-
-This means that the version number of the local checkout is significant and will
-affect whether the patch is used. Our manifest declared `uuid = "1.0"` which
-means we'll only resolve to `>= 1.0.0, < 2.0.0`, and Cargo's greedy resolution
-algorithm also means that we'll resolve to the maximum version within that
-range. Typically this doesn't matter as the version of the git repository will
-already be greater or match the maximum version published on crates.io, but it's
-important to keep this in mind!
-
-In any case, typically all you need to do now is:
-
-```console
-$ cargo build
- Compiling uuid v1.0.0 (.../uuid)
- Compiling my-library v0.1.0 (.../my-library)
- Finished dev [unoptimized + debuginfo] target(s) in 0.32 secs
-```
-
-And that's it! You're now building with the local version of `uuid` (note the
-path in parentheses in the build output). If you don't see the local path version getting
-built then you may need to run `cargo update -p uuid --precise $version` where
-`$version` is the version of the locally checked out copy of `uuid`.
-
-Once you've fixed the bug you originally found the next thing you'll want to do
-is to likely submit that as a pull request to the `uuid` crate itself. Once
-you've done this then you can also update the `[patch]` section. The listing
-inside of `[patch]` is just like the `[dependencies]` section, so once your pull
-request is merged you could change your `path` dependency to:
-
-```toml
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-[uuid-repository]: https://github.com/rust-lang-nursery/uuid
-
-### Working with an unpublished minor version
-
-Let's now shift gears a bit from bug fixes to adding features. While working on
-`my-library` you discover that a whole new feature is needed in the `uuid`
-crate. You've implemented this feature, tested it locally above with `[patch]`,
-and submitted a pull request. Let's go over how you continue to use and test it
-before it's actually published.
-
-Let's also say that the current version of `uuid` on crates.io is `1.0.0`, but
-since then the master branch of the git repository has updated to `1.0.1`. This
-branch includes your new feature you submitted previously. To use this
-repository we'll edit our `Cargo.toml` to look like
-
-```toml
-[package]
-name = "my-library"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-uuid = "1.0.1"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-Note that our local dependency on `uuid` has been updated to `1.0.1` as it's
-what we'll actually require once the crate is published. This version doesn't
-exist on crates.io, though, so we provide it with the `[patch]` section of the
-manifest.
+> **Note**: [crates.io] does not allow packages to be published with `path`
+> dependencies (`path` [dev-dependencies] are ignored). See the [Multiple
+> locations](#multiple-locations) section for a fallback alternative.
-Now when our library is built it'll fetch `uuid` from the git repository and
-resolve to 1.0.1 inside the repository instead of trying to download a version
-from crates.io. Once 1.0.1 is published on crates.io the `[patch]` section can
-be deleted.
+### Multiple locations
-It's also worth noting that `[patch]` applies *transitively*. Let's say you use
-`my-library` in a larger package, such as:
+It is possible to specify both a registry version and a `git` or `path`
+location. The `git` or `path` dependency will be used locally (in which case
+the `version` is ignored), and when published to a registry like [crates.io],
+it will use the registry version. Other combinations are not allowed.
+Examples:
```toml
-[package]
-name = "my-binary"
-version = "0.1.0"
-authors = ["..."]
-
-[dependencies]
-my-library = { git = 'https://example.com/git/my-library' }
-uuid = "1.0"
-
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid' }
-```
-
-Remember that `[patch]` is applicable *transitively* but can only be defined at
-the *top level* so we consumers of `my-library` have to repeat the `[patch]` section
-if necessary. Here, though, the new `uuid` crate applies to *both* our dependency on
-`uuid` and the `my-library -> uuid` dependency. The `uuid` crate will be resolved to
-one version for this entire crate graph, 1.0.1, and it'll be pulled from the git
-repository.
-
-#### Overriding repository URL
-
-In case the dependency you want to override isn't loaded from `crates.io`, you'll have to change a bit how you use `[patch]`:
-
-```toml
-[patch."https://github.com/your/repository"]
-my-library = { path = "../my-library/path" }
-```
-
-And that's it!
-
-### Prepublishing a breaking change
-
-As a final scenario, let's take a look at working with a new major version of a
-crate, typically accompanied with breaking changes. Sticking with our previous
-crates, this means that we're going to be creating version 2.0.0 of the `uuid`
-crate. After we've submitted all changes upstream we can update our manifest for
-`my-library` to look like:
-
-```toml
-[dependencies]
-uuid = "2.0"
-
-[patch.crates-io]
-uuid = { git = "https://github.com/rust-lang-nursery/uuid", branch = "2.0.0" }
-```
-
-And that's it! Like with the previous example the 2.0.0 version doesn't actually
-exist on crates.io but we can still put it in through a git dependency through
-the usage of the `[patch]` section. As a thought exercise let's take another
-look at the `my-binary` manifest from above again as well:
-
-```toml
-[package]
-name = "my-binary"
-version = "0.1.0"
-authors = ["..."]
-
[dependencies]
-my-library = { git = 'https://example.com/git/my-library' }
-uuid = "1.0"
+# Uses `my-bitflags` when used locally, and uses
+# version 1.0 from crates.io when published.
+bitflags = { path = "my-bitflags", version = "1.0" }
-[patch.crates-io]
-uuid = { git = 'https://github.com/rust-lang-nursery/uuid', branch = '2.0.0' }
+# Uses the given git repo when used locally, and uses
+# version 1.0 from crates.io when published.
+smallvec = { git = "https://github.com/servo/rust-smallvec", version = "1.0" }
```
-Note that this will actually resolve to two versions of the `uuid` crate. The
-`my-binary` crate will continue to use the 1.x.y series of the `uuid` crate but
-the `my-library` crate will use the 2.0.0 version of `uuid`. This will allow you
-to gradually roll out breaking changes to a crate through a dependency graph
-without being force to update everything all at once.
-
-### Overriding with local dependencies
-
-Sometimes you're only temporarily working on a crate and you don't want to have
-to modify `Cargo.toml` like with the `[patch]` section above. For this use
-case Cargo offers a much more limited version of overrides called **path
-overrides**.
-
-Path overrides are specified through `.cargo/config` instead of `Cargo.toml`,
-and you can find [more documentation about this configuration][config-docs].
-Inside of `.cargo/config` you'll specify a key called `paths`:
-
-[config-docs]: config.md
-
-```toml
-paths = ["/path/to/uuid"]
-```
-
-This array should be filled with directories that contain a `Cargo.toml`. In
-this instance, we’re just adding `uuid`, so it will be the only one that’s
-overridden. This path can be either absolute or relative to the directory that
-contains the `.cargo` folder.
-
-Path overrides are more restricted than the `[patch]` section, however, in
-that they cannot change the structure of the dependency graph. When a
-path replacement is used then the previous set of dependencies
-must all match exactly to the new `Cargo.toml` specification. For example this
-means that path overrides cannot be used to test out adding a dependency to a
-crate, instead `[patch]` must be used in that situation. As a result usage of a
-path override is typically isolated to quick bug fixes rather than larger
-changes.
-
-Note: using a local configuration to override paths will only work for crates
-that have been published to [crates.io]. You cannot use this feature to tell
-Cargo how to find local unpublished crates.
+One example where this can be useful is when you have split up a library into
+multiple packages within the same workspace. You can then use `path`
+dependencies to point to the local packages within the workspace to use the
+local version during development, and then use the [crates.io] version once it
+is published. This is similar to specifying an
+[override](overriding-dependencies.md), but only applies to this one
+dependency declaration.
### Platform specific dependencies
-
Platform-specific dependencies take the same format, but are listed under a
`target` section. Normally Rust-like [`#[cfg]`
syntax](../../reference/conditional-compilation.html) will be used to define
@@ -470,11 +252,19 @@ If you want to know which cfg targets are available on your platform, run
targets are available for another platform, such as 64-bit Windows,
run `rustc --print=cfg --target=x86_64-pc-windows-msvc`.
-Unlike in your Rust source code,
-you cannot use `[target.'cfg(feature = "my_crate")'.dependencies]` to add
-dependencies based on optional crate features.
-Use [the `[features]` section](manifest.md#the-features-section)
-instead.
+Unlike in your Rust source code, you cannot use
+`[target.'cfg(feature = "fancy-feature")'.dependencies]` to add dependencies
+based on optional features. Use [the `[features]` section](features.md)
+instead:
+
+```toml
+[dependencies]
+foo = { version = "1.0", optional = true }
+bar = { version = "1.0", optional = true }
+
+[features]
+fancy-feature = ["foo", "bar"]
+```
The same applies to `cfg(debug_assertions)`, `cfg(test)` and `cfg(prog_macro)`.
These values will not work as expected and will always have the default value
@@ -492,6 +282,8 @@ winhttp = "0.4.0"
openssl = "1.0.1"
```
+#### Custom target specifications
+
If you’re using a custom target specification (such as `--target
foo/bar.json`), use the base filename without the `.json` extension:
@@ -504,6 +296,8 @@ openssl = "1.0.1"
native = { path = "native/i686" }
```
+> **Note**: Custom target specifications are not usable on the stable channel.
+
### Development dependencies
You can add a `[dev-dependencies]` section to your `Cargo.toml` whose format
@@ -530,7 +324,11 @@ example:
mio = "0.0.1"
```
-[crates.io]: https://crates.io/
+> **Note**: When a package is published, only dev-dependencies that specify a
+> `version` will be included in the published crate. For most use cases,
+> dev-dependencies are not needed when published, though some users (like OS
+> packagers) may want to run tests within a crate, so providing a `version` if
+> possible can still be beneficial.
### Build dependencies
@@ -564,8 +362,8 @@ default-features = false # do not include the default features, and optionally
features = ["secure-password", "civet"]
```
-More information about features can be found in the
-[manifest documentation](manifest.md#the-features-section).
+More information about features can be found in the [features
+chapter](features.md).
### Renaming dependencies in `Cargo.toml`
@@ -625,3 +423,27 @@ following to the above manifest:
[features]
log-debug = ['foo/log-debug'] # using 'bar/log-debug' would be an error!
```
+
+[crates.io]: https://crates.io/
+[dev-dependencies]: #development-dependencies
+
+
+
+
diff --git a/src/doc/src/reference/workspaces.md b/src/doc/src/reference/workspaces.md
new file mode 100644
index 00000000000..44df763c8d1
--- /dev/null
+++ b/src/doc/src/reference/workspaces.md
@@ -0,0 +1,93 @@
+## Workspaces
+
+A *workspace* is a collection of one or more packages that share common
+dependency resolution (with a shared `Cargo.lock`), output directory, and
+various settings such as profiles. Packages that are part of a workspaces are
+called *workspace members*.
+
+A workspace can be created by adding a [`[workspace]`
+section](#the-workspace-section) to `Cargo.toml`. This can be added to a
+`Cargo.toml` that already defines a `[package]`, in which case the package is
+the *root package* of the workspace. The *workspace root* is the directory
+where the workspace's `Cargo.toml` is located.
+
+Alternatively, a `Cargo.toml` file can be created with a `[workspace]` section
+but without a [`[package]` section][package]. This is called a *virtual
+manifest*. This is typically useful when there isn't a "primary" package, or
+you want to keep all the packages organized in separate directories.
+
+The key points of workspaces are:
+
+* All packages share a common `Cargo.lock` file which resides in the
+ *workspace root*.
+* All packages share a common [output directory], which defaults to a
+ directory named `target` in the *workspace root*.
+* The [`[patch]`][patch], [`[replace]`][replace] and [`[profile.*]`][profiles]
+ sections in `Cargo.toml` are only recognized in the *root* manifest, and
+ ignored in member crates' manifests.
+
+### The `[workspace]` section
+
+The `[workspace]` table in `Cargo.toml` defines which packages are members of
+the workspace:
+
+```toml
+[workspace]
+members = ["member1", "path/to/member2", "crates/*"]
+exclude = ["crates/foo", "path/to/other"]
+```
+
+All [`path` dependencies] residing in the workspace directory automatically
+become members. Additional members can be listed with the `members` key, which
+should be an array of strings containing directories with `Cargo.toml` files.
+
+The `members` list also supports [globs] to match multiple paths, using
+typical filename glob patterns like `*` and `?`.
+
+The `exclude` key can be used to prevent paths from being included in a
+workspace. This can be useful if some path dependencies aren't desired to be
+in the workspace at all, or using a glob pattern and you want to remove a
+directory.
+
+An empty `[workspace]` table can be used with a `[package]` to conveniently
+create a workspace with the package and all of its path dependencies.
+
+### Workspace selection
+
+When inside a subdirectory within the workspace, Cargo will automatically
+search the parent directories for a `Cargo.toml` file with a `[workspace]`
+definition to determine which workspace to use. The [`package.workspace`]
+manifest key can be used in member crates to point at a workspace's root to
+override this automatic search. The manual setting can be useful if the member
+is not inside a subdirectory of the workspace root.
+
+### Package selection
+
+In a workspace, package-related cargo commands like [`cargo build`] can use
+the `-p` / `--package` or `--workspace` command-line flags to determine which
+packages to operate on. If neither of those flags are specified, Cargo will
+use the package in the current working directory. If the current directory is
+a virtual workspace, it will apply to all members (as if `--workspace` were
+specified on the command-line).
+
+The optional `default-members` key can be specified to set the members to
+operate on when in the workspace root and the package selection flags are not
+used:
+
+```toml
+[workspace]
+members = ["path/to/member1", "path/to/member2", "path/to/member3/*"]
+default-members = ["path/to/member2", "path/to/member3/foo"]
+```
+
+When specified, `default-members` must expand to a subset of `members`.
+
+[package]: manifest.md#the-package-section
+[output directory]: ../guide/build-cache.md
+[patch]: overriding-dependencies.md#the-patch-section
+[replace]: overriding-dependencies.md#the-replace-section
+[profiles]: profiles.md
+[`path` dependencies]: specifying-dependencies.md#specifying-path-dependencies
+[`package.workspace`]: manifest.md#the-workspace-field
+[globs]: https://docs.rs/glob/0.3.0/glob/struct.Pattern.html
+[`cargo build`]: ../commands/cargo-build.md
diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1
index 626facce232..3d4bdc35792 100644
--- a/src/etc/man/cargo-bench.1
+++ b/src/etc/man/cargo-bench.1
@@ -2,12 +2,12 @@
.\" Title: cargo-bench
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-11-15
+.\" Date: 2019-12-05
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-BENCH" "1" "2019-11-15" "\ \&" "\ \&"
+.TH "CARGO\-BENCH" "1" "2019-12-05" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -251,7 +251,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -275,6 +276,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.SS "Output Options"
.sp
@@ -567,4 +573,4 @@ cargo bench \-\-bench bench_name \-\- modname::some_benchmark
.RE
.SH "SEE ALSO"
.sp
-\fBcargo\fP(1), \fBcargo\-test\fP(1)
+\fBcargo\fP(1), \fBcargo\-test\fP(1)
\ No newline at end of file
diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1
index 5a8565b8b3e..17ed8d17913 100644
--- a/src/etc/man/cargo-build.1
+++ b/src/etc/man/cargo-build.1
@@ -151,7 +151,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -175,6 +176,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP
diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1
index 93c4efef929..8513a156584 100644
--- a/src/etc/man/cargo-check.1
+++ b/src/etc/man/cargo-check.1
@@ -155,7 +155,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -179,6 +180,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP
diff --git a/src/etc/man/cargo-clean.1 b/src/etc/man/cargo-clean.1
index cf52542a7a7..7ad930ab1c7 100644
--- a/src/etc/man/cargo-clean.1
+++ b/src/etc/man/cargo-clean.1
@@ -82,6 +82,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.SS "Display Options"
.sp
diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1
index 726db633ca2..60c9d825236 100644
--- a/src/etc/man/cargo-doc.1
+++ b/src/etc/man/cargo-doc.1
@@ -2,12 +2,12 @@
.\" Title: cargo-doc
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-11-11
+.\" Date: 2019-12-05
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-DOC" "1" "2019-11-11" "\ \&" "\ \&"
+.TH "CARGO\-DOC" "1" "2019-12-05" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -123,7 +123,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -147,6 +148,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP
diff --git a/src/etc/man/cargo-fetch.1 b/src/etc/man/cargo-fetch.1
index 6bada865551..1442fa02eb6 100644
--- a/src/etc/man/cargo-fetch.1
+++ b/src/etc/man/cargo-fetch.1
@@ -2,12 +2,12 @@
.\" Title: cargo-fetch
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-09-05
+.\" Date: 2019-11-11
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-FETCH" "1" "2019-09-05" "\ \&" "\ \&"
+.TH "CARGO\-FETCH" "1" "2019-11-11" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -60,6 +60,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.SS "Display Options"
.sp
diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1
index 3a493f9265c..e86d48079d0 100644
--- a/src/etc/man/cargo-fix.1
+++ b/src/etc/man/cargo-fix.1
@@ -2,12 +2,12 @@
.\" Title: cargo-fix
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-09-05
+.\" Date: 2019-12-19
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-FIX" "1" "2019-09-05" "\ \&" "\ \&"
+.TH "CARGO\-FIX" "1" "2019-12-19" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -53,20 +53,24 @@ cargo fix \-\-edition
.fi
.if n .RE
.sp
-which behaves the same as \fBcargo check \-\-all\-targets\fP. Similarly if you\(cqd like
-to fix code for different platforms you can do:
+which behaves the same as \fBcargo check \-\-all\-targets\fP.
+.sp
+\fBcargo fix\fP is only capable of fixing code that is normally compiled with
+\fBcargo check\fP. If code is conditionally enabled with optional features, you
+will need to enable those features for that code to be analyzed:
.sp
.if n .RS 4
.nf
-cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu
+cargo fix \-\-edition \-\-features foo
.fi
.if n .RE
.sp
-or if your crate has optional features:
+Similarly, other \fBcfg\fP expressions like platform\-specific code will need to
+pass \fB\-\-target\fP to fix code for the given target.
.sp
.if n .RS 4
.nf
-cargo fix \-\-edition \-\-no\-default\-features \-\-features foo
+cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu
.fi
.if n .RE
.sp
@@ -225,7 +229,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -249,6 +254,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP
diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1
index 2dfdff5f5ec..c733b4edf03 100644
--- a/src/etc/man/cargo-install.1
+++ b/src/etc/man/cargo-install.1
@@ -2,12 +2,12 @@
.\" Title: cargo-install
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-11-04
+.\" Date: 2019-12-05
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-INSTALL" "1" "2019-11-04" "\ \&" "\ \&"
+.TH "CARGO\-INSTALL" "1" "2019-12-05" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -302,7 +302,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -326,6 +327,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-debug\fP
@@ -511,4 +517,4 @@ cargo install \-\-list
.RE
.SH "SEE ALSO"
.sp
-\fBcargo\fP(1), \fBcargo\-uninstall\fP(1), \fBcargo\-search\fP(1), \fBcargo\-publish\fP(1)
+\fBcargo\fP(1), \fBcargo\-uninstall\fP(1), \fBcargo\-search\fP(1), \fBcargo\-publish\fP(1)
\ No newline at end of file
diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1
index 7589c86a2f5..2529f686ade 100644
--- a/src/etc/man/cargo-metadata.1
+++ b/src/etc/man/cargo-metadata.1
@@ -2,12 +2,12 @@
.\" Title: cargo-metadata
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-10-28
+.\" Date: 2019-12-05
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-METADATA" "1" "2019-10-28" "\ \&" "\ \&"
+.TH "CARGO\-METADATA" "1" "2019-12-05" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -324,7 +324,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1
index b1283fb76ec..f85d664355b 100644
--- a/src/etc/man/cargo-package.1
+++ b/src/etc/man/cargo-package.1
@@ -2,12 +2,12 @@
.\" Title: cargo-package
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-10-28
+.\" Date: 2019-12-19
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-PACKAGE" "1" "2019-10-28" "\ \&" "\ \&"
+.TH "CARGO\-PACKAGE" "1" "2019-12-19" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -132,6 +132,19 @@ about the current VCS checkout hash if available (not included with
. IP " 3." 4.2
.\}
Extract the \fB.crate\fP file and build it to verify it can build.
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+. sp -1
+. IP \(bu 2.3
+.\}
+This will rebuild your package from scratch to ensure that it can be
+built from a pristine state. The \fB\-\-no\-verify\fP flag can be used to skip
+this step.
+.RE
.RE
.sp
.RS 4
@@ -186,6 +199,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-target\-dir\fP \fIDIRECTORY\fP
@@ -206,7 +224,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1
index 2f337d4eb09..fe060251c5e 100644
--- a/src/etc/man/cargo-publish.1
+++ b/src/etc/man/cargo-publish.1
@@ -149,6 +149,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-target\-dir\fP \fIDIRECTORY\fP
@@ -169,7 +174,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1
index 410f3a9521a..d49aa0e9573 100644
--- a/src/etc/man/cargo-run.1
+++ b/src/etc/man/cargo-run.1
@@ -75,7 +75,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -99,6 +100,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP
diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1
index 17b7722c86c..199dba235ac 100644
--- a/src/etc/man/cargo-rustc.1
+++ b/src/etc/man/cargo-rustc.1
@@ -2,12 +2,12 @@
.\" Title: cargo-rustc
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-09-05
+.\" Date: 2019-12-19
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-RUSTC" "1" "2019-09-05" "\ \&" "\ \&"
+.TH "CARGO\-RUSTC" "1" "2019-12-19" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -51,7 +51,9 @@ arguments are provided. If more than one target is available for the current
package the filters of \fB\-\-lib\fP, \fB\-\-bin\fP, etc, must be used to select which
target is compiled.
To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fP
-environment variable or the \fBbuild.rustflags\fP
+.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable" " "
+or the
+\fBbuild.rustflags\fP \c
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
.SH "OPTIONS"
.SS "Package Selection"
@@ -144,7 +146,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -168,6 +171,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP
diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1
index 668b083e9f0..3125cd1abbd 100644
--- a/src/etc/man/cargo-rustdoc.1
+++ b/src/etc/man/cargo-rustdoc.1
@@ -2,12 +2,12 @@
.\" Title: cargo-rustdoc
.\" Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.10
-.\" Date: 2019-11-11
+.\" Date: 2019-12-19
.\" Manual: \ \&
.\" Source: \ \&
.\" Language: English
.\"
-.TH "CARGO\-RUSTDOC" "1" "2019-11-11" "\ \&" "\ \&"
+.TH "CARGO\-RUSTDOC" "1" "2019-12-19" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.ss \n[.ss] 0
@@ -51,8 +51,10 @@ arguments are provided. If more than one target is available for the current
package the filters of \fB\-\-lib\fP, \fB\-\-bin\fP, etc, must be used to select which
target is compiled.
To pass flags to all rustdoc processes spawned by Cargo, use the
-\fBRUSTDOCFLAGS\fP environment variable or the \fBbuild.rustdocflags\fP configuration
-option.
+\fBRUSTDOCFLAGS\fP \c
+.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable"
+or the \fBbuild.rustdocflags\fP \c
+.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
.SH "OPTIONS"
.SS "Documentation Options"
.sp
@@ -154,7 +156,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -178,6 +181,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP
diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1
index 476ea5f254f..5b1b0b94cc3 100644
--- a/src/etc/man/cargo-test.1
+++ b/src/etc/man/cargo-test.1
@@ -287,7 +287,8 @@ every selected package.
.RS 4
Space or comma separated list of features to activate. These features only
apply to the current directory\(cqs package. Features of direct dependencies
-may be enabled with \fB/\fP syntax.
+may be enabled with \fB/\fP syntax. This flag may be
+specified multiple times, which enables all specified features.
.RE
.sp
\fB\-\-all\-features\fP
@@ -311,6 +312,11 @@ list of supported targets.
.sp
This may also be specified with the \fBbuild.target\fP
.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "."
+.sp
+Note that specifying this flag makes Cargo run in a different mode where the
+target artifacts are placed in a separate directory. See the
+.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " "
+documentation for more details.
.RE
.sp
\fB\-\-release\fP