mirror of
https://github.com/rust-lang/cargo
synced 2024-10-14 03:32:39 +00:00
Auto merge of #7733 - ehuss:doc-updates, r=Eh2406
Various doc updates This is a collection of documentation updates that have been in my todo list for a while. Each change is in a separate commit. The "features" chapter will probably get significant changes in the future, as it is pretty bare right now. Similarly the "workspace" chapter could probably use more examples. Closes #3062 Closes #3817 Closes #3971 Closes #4212 Closes #4438 Closes #4756 Closes #5822 Closes #6913 Closes #7055
This commit is contained in:
bors
commit
741f0e586a
|
|
@ -28,15 +28,19 @@ 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` 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
|
||||
|
||||
Similarly, other `cfg` expressions like platform-specific code will need to
|
||||
pass `--target` to fix code for the given target.
|
||||
|
||||
cargo fix --edition --target x86_64-pc-windows-gnu
|
||||
|
||||
or if your crate has optional features:
|
||||
|
||||
cargo fix --edition --no-default-features --features foo
|
||||
|
||||
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
|
||||
https://github.com/rust-lang/cargo
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -213,7 +213,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -241,6 +242,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -142,7 +142,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -170,6 +171,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -146,7 +146,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -174,6 +175,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -73,6 +73,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -124,7 +124,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -152,6 +153,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -50,6 +50,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -34,8 +34,21 @@ executing:</p>
|
|||
</div>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>which behaves the same as <code>cargo check --all-targets</code>. Similarly if you’d like
|
||||
to fix code for different platforms you can do:</p>
|
||||
<p>which behaves the same as <code>cargo check --all-targets</code>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p><code>cargo fix</code> is only capable of fixing code that is normally compiled with
|
||||
<code>cargo check</code>. If code is conditionally enabled with optional features, you
|
||||
will need to enable those features for that code to be analyzed:</p>
|
||||
</div>
|
||||
<div class="literalblock">
|
||||
<div class="content">
|
||||
<pre>cargo fix --edition --features foo</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Similarly, other <code>cfg</code> expressions like platform-specific code will need to
|
||||
pass <code>--target</code> to fix code for the given target.</p>
|
||||
</div>
|
||||
<div class="literalblock">
|
||||
<div class="content">
|
||||
|
|
@ -43,14 +56,6 @@ to fix code for different platforms you can do:</p>
|
|||
</div>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>or if your crate has optional features:</p>
|
||||
</div>
|
||||
<div class="literalblock">
|
||||
<div class="content">
|
||||
<pre>cargo fix --edition --no-default-features --features foo</pre>
|
||||
</div>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>If you encounter any problems with <code>cargo fix</code> or otherwise have any questions
|
||||
or feature requests please don’t hesitate to file an issue at
|
||||
<a href="https://github.com/rust-lang/cargo" class="bare">https://github.com/rust-lang/cargo</a></p>
|
||||
|
|
@ -217,7 +222,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -245,6 +251,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -212,7 +212,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -240,6 +241,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--debug</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -321,7 +321,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -59,6 +59,15 @@ about the current VCS checkout hash if available (not included with
|
|||
</li>
|
||||
<li>
|
||||
<p>Extract the <code>.crate</code> file and build it to verify it can build.</p>
|
||||
<div class="ulist">
|
||||
<ul>
|
||||
<li>
|
||||
<p>This will rebuild your package from scratch to ensure that it can be
|
||||
built from a pristine state. The <code>--no-verify</code> flag can be used to skip
|
||||
this step.</p>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</li>
|
||||
<li>
|
||||
<p>Check that build scripts did not modify any source files.</p>
|
||||
|
|
@ -117,6 +126,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--target-dir</strong> <em>DIRECTORY</em></dt>
|
||||
<dd>
|
||||
|
|
@ -140,7 +154,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -110,6 +110,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--target-dir</strong> <em>DIRECTORY</em></dt>
|
||||
<dd>
|
||||
|
|
@ -133,7 +138,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -76,7 +76,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -104,6 +105,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ arguments are provided. If more than one target is available for the current
|
|||
package the filters of <code>--lib</code>, <code>--bin</code>, etc, must be used to select which
|
||||
target is compiled.
|
||||
To pass flags to all compiler processes spawned by Cargo, use the <code>RUSTFLAGS</code>
|
||||
environment variable or the <code>build.rustflags</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
<a href="../reference/environment-variables.html">environment variable</a> or the
|
||||
<code>build.rustflags</code> <a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -137,7 +137,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -165,6 +166,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -31,8 +31,8 @@ arguments are provided. If more than one target is available for the current
|
|||
package the filters of <code>--lib</code>, <code>--bin</code>, etc, must be used to select which
|
||||
target is compiled.
|
||||
To pass flags to all rustdoc processes spawned by Cargo, use the
|
||||
<code>RUSTDOCFLAGS</code> environment variable or the <code>build.rustdocflags</code> configuration
|
||||
option.</p>
|
||||
<code>RUSTDOCFLAGS</code> <a href="../reference/environment-variables.html">environment variable</a>
|
||||
or the <code>build.rustdocflags</code> <a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -152,7 +152,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -180,6 +181,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -233,7 +233,8 @@ every selected package.</p>
|
|||
<dd>
|
||||
<p>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 <code><dep-name>/<feature-name></code> syntax.</p>
|
||||
may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.</p>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--all-features</strong></dt>
|
||||
<dd>
|
||||
|
|
@ -261,6 +262,11 @@ list of supported targets.</p>
|
|||
<p>This may also be specified with the <code>build.target</code>
|
||||
<a href="../reference/config.html">config value</a>.</p>
|
||||
</div>
|
||||
<div class="paragraph">
|
||||
<p>Note that specifying this flag makes Cargo run in a different mode where the
|
||||
target artifacts are placed in a separate directory. See the
|
||||
<a href="../guide/build-cache.html">build cache</a> documentation for more details.</p>
|
||||
</div>
|
||||
</dd>
|
||||
<dt class="hdlist1"><strong>--release</strong></dt>
|
||||
<dd>
|
||||
|
|
|
|||
|
|
@ -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 `<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*::
|
||||
Activate all available features of all selected packages.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
----------|------------
|
||||
<code style="white-space: nowrap">target/debug/</code> | Contains debug build output.
|
||||
<code style="white-space: nowrap">target/release/</code> | 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
|
||||
----------|--------
|
||||
<code style="white-space: nowrap">target/<triple>/debug/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/debug/</code>
|
||||
<code style="white-space: nowrap">target/<triple>/release/</code> | <code style="white-space: nowrap">target/thumbv7em-none-eabihf/release/</code>
|
||||
|
||||
> **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
|
||||
----------|------------
|
||||
<code style="white-space: nowrap">target/debug/</code> | Contains the output of the package being built (the `[[bin]]` executables and `[lib]` library targets).
|
||||
<code style="white-space: nowrap">target/debug/examples/</code> | Contains examples (`[[example]]` targets).
|
||||
|
||||
Some commands place their output in dedicated directories in the top level of
|
||||
the `target` directory:
|
||||
|
||||
Directory | Description
|
||||
----------|------------
|
||||
<code style="white-space: nowrap">target/doc/</code> | Contains rustdoc documentation ([`cargo doc`]).
|
||||
<code style="white-space: nowrap">target/package/</code> | 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
|
||||
----------|------------
|
||||
<code style="white-space: nowrap">target/debug/deps/</code> | Dependencies and other artifacts.
|
||||
<code style="white-space: nowrap">target/debug/incremental/</code> | `rustc` [incremental output], a cache used to speed up subsequent builds.
|
||||
<code style="white-space: nowrap">target/debug/build/</code> | 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
These are explained in more detail in the [manifest
|
||||
description](../reference/manifest.md#the-project-layout).
|
||||
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.
|
||||
|
||||
[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
|
||||
|
|
|
|||
3
src/doc/src/images/profile-selection.svg
Normal file
3
src/doc/src/images/profile-selection.svg
Normal file
File diff suppressed because one or more lines are too long
|
After Width: | Height: | Size: 11 KiB |
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<a id="rerun-if-changed"></a>
|
||||
#### `cargo:rerun-if-changed=PATH`
|
||||
|
|
|
|||
372
src/doc/src/reference/cargo-targets.md
Normal file
372
src/doc/src/reference/cargo-targets.md
Normal file
|
|
@ -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
|
||||
<bin-name>` 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 <example-name>` option. Library examples can be built with
|
||||
[`cargo build`] with the `--example <example-name>` option. [`cargo install`]
|
||||
with the `--example <example-name>` 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
|
||||
|
|
@ -207,8 +207,8 @@ the `<triple>` 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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
134
src/doc/src/reference/features.md
Normal file
134
src/doc/src/reference/features.md
Normal file
|
|
@ -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/
|
||||
|
|
@ -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)
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
349
src/doc/src/reference/overriding-dependencies.md
Normal file
349
src/doc/src/reference/overriding-dependencies.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
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`
|
||||
- [`authors`]
|
||||
- [`license` or `license-file`]
|
||||
- [`description`]
|
||||
- [`homepage`]
|
||||
- [`documentation`]
|
||||
- [`repository`]
|
||||
- [`readme`]
|
||||
|
||||
It would also be a good idea to include some `keywords` and `categories`,
|
||||
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/
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
> **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.
|
||||
|
||||
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.
|
||||
### Multiple locations
|
||||
|
||||
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.
|
||||
|
||||
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/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:
|
||||
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
|
||||
[dependencies]
|
||||
uuid = "2.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" }
|
||||
```
|
||||
|
||||
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/rust-lang-nursery/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.
|
||||
|
||||
### 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
|
||||
|
||||
<script>
|
||||
(function() {
|
||||
var fragments = {
|
||||
"#overriding-dependencies": "overriding-dependencies.html",
|
||||
"#testing-a-bugfix": "overriding-dependencies.html#testing-a-bugfix",
|
||||
"#working-with-an-unpublished-minor-version": "overriding-dependencies.html#working-with-an-unpublished-minor-version",
|
||||
"#overriding-repository-url": "overriding-dependencies.html#overriding-repository-url",
|
||||
"#prepublishing-a-breaking-change": "overriding-dependencies.html#prepublishing-a-breaking-change",
|
||||
"#overriding-with-local-dependencies": "overriding-dependencies.html#paths-overrides",
|
||||
};
|
||||
var target = fragments[window.location.hash];
|
||||
if (target) {
|
||||
var url = window.location.toString();
|
||||
var base = url.substring(0, url.lastIndexOf('/'));
|
||||
window.location.replace(base + "/" + target);
|
||||
}
|
||||
})();
|
||||
</script>
|
||||
|
||||
|
||||
|
|
|
|||
93
src/doc/src/reference/workspaces.md
Normal file
93
src/doc/src/reference/workspaces.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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)
|
||||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,8 +53,20 @@ 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 \-\-features foo
|
||||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
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
|
||||
|
|
@ -62,14 +74,6 @@ cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu
|
|||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
or if your crate has optional features:
|
||||
.sp
|
||||
.if n .RS 4
|
||||
.nf
|
||||
cargo fix \-\-edition \-\-no\-default\-features \-\-features foo
|
||||
.fi
|
||||
.if n .RE
|
||||
.sp
|
||||
If you encounter any problems with \fBcargo fix\fP or otherwise have any questions
|
||||
or feature requests please don\(cqt hesitate to file an issue at
|
||||
.URL "https://github.com/rust\-lang/cargo" "" ""
|
||||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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)
|
||||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\fP syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.
|
||||
.RE
|
||||
.sp
|
||||
\fB\-\-all\-features\fP
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\fP syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.
|
||||
.RE
|
||||
.sp
|
||||
\fB\-\-all\-features\fP
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\fP syntax. This flag may be
|
||||
specified multiple times, which enables all specified features.
|
||||
.RE
|
||||
.sp
|
||||
\fB\-\-all\-features\fP
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
|
|
@ -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<dep\-name>/<feature\-name>\fP syntax.
|
||||
may be enabled with \fB<dep\-name>/<feature\-name>\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
|
||||
|
|
|
|||
Loading…
Reference in a new issue