Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Various doc updates #7733

Merged
merged 28 commits into from
Dec 22, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
4661c9a
Mention --offline in the FAQ entry on offline.
ehuss Dec 18, 2019
bb3f132
Mention that `--features` can be specified multiple times.
ehuss Dec 18, 2019
97b833e
Add links for rustflags/rustdocflags.
ehuss Dec 18, 2019
64f605b
Document the target directory layout.
ehuss Dec 18, 2019
98752b0
Fix awkward comma in sentence.
ehuss Dec 18, 2019
da881b7
Simplify some crates.io links.
ehuss Dec 18, 2019
2a4aa42
Be clearer about which fields are optional/required.
ehuss Dec 19, 2019
b884b0d
Fix minor `vendor` mistake in glossary.
ehuss Dec 19, 2019
07aed50
Fix some chapter links missing from index pages.
ehuss Dec 19, 2019
fee34fc
Clarify `cargo fix` behavior with features.
ehuss Dec 19, 2019
765c80d
Describe dep-info files a little better.
ehuss Dec 19, 2019
c4033d3
Mention `cargo metadata` for custom subcommands.
ehuss Dec 19, 2019
14f7a91
Build script change detection: link to include/exclude
ehuss Dec 19, 2019
82bcbde
Break up the Platform specific dependencies section.
ehuss Dec 19, 2019
18e02da
Show example for 'cfg(feature="foo")' dependency alternative.
ehuss Dec 19, 2019
caf88f5
Try to make it a little clearer that cargo package/publish will rebui…
ehuss Dec 19, 2019
47a46ae
Try to be clearer about how `--target` is different.
ehuss Dec 19, 2019
e958fe6
Clarify that [replace] requires a version number.
ehuss Dec 19, 2019
018b5f5
Document that [replace] should not be used.
ehuss Dec 19, 2019
e5bc8cc
Try to clarify dev/test profile selection.
ehuss Dec 20, 2019
0a5f54b
Don't describe the package layout twice.
ehuss Dec 20, 2019
0f99322
Move cargo targets to a new chapter.
ehuss Dec 21, 2019
f453bed
Move workspaces to a separate chapter.
ehuss Dec 21, 2019
dc81356
Move features to a separate chapter.
ehuss Dec 21, 2019
543e381
Add a table of contents for the manifest.
ehuss Dec 21, 2019
d1d0837
Move overriding dependencies into a separate chapter.
ehuss Dec 21, 2019
c2ff762
Add build script examples to reference index.
ehuss Dec 21, 2019
493eb34
Note that harness=false enables cfg(test).
ehuss Dec 21, 2019
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 9 additions & 5 deletions src/doc/man/cargo-fix.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,18 @@ executing:

cargo fix --edition

which behaves the same as `cargo check --all-targets`. Similarly if you'd like
to fix code for different platforms you can do:
which behaves the same as `cargo check --all-targets`.

cargo fix --edition --target x86_64-pc-windows-gnu
`cargo fix` is only capable of fixing code that is normally compiled with
`cargo check`. If code is conditionally enabled with optional features, you
will need to enable those features for that code to be analyzed:

cargo fix --edition --features foo

or if your crate has optional features:
Similarly, other `cfg` expressions like platform-specific code will need to
pass `--target` to fix code for the given target.

cargo fix --edition --no-default-features --features foo
cargo fix --edition --target x86_64-pc-windows-gnu

If you encounter any problems with `cargo fix` or otherwise have any questions
or feature requests please don't hesitate to file an issue at
Expand Down
3 changes: 3 additions & 0 deletions src/doc/man/cargo-package.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
4 changes: 2 additions & 2 deletions src/doc/man/cargo-rustc.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
4 changes: 2 additions & 2 deletions src/doc/man/cargo-rustdoc.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 7 additions & 1 deletion src/doc/man/generated/cargo-bench.html
Original file line number Diff line number Diff line change
Expand Up @@ -213,7 +213,8 @@ <h3 id="cargo_bench_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -241,6 +242,11 @@ <h3 id="cargo_bench_compilation_options">Compilation Options</h3>
<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>
Expand Down
8 changes: 7 additions & 1 deletion src/doc/man/generated/cargo-build.html
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,8 @@ <h3 id="cargo_build_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -170,6 +171,11 @@ <h3 id="cargo_build_compilation_options">Compilation Options</h3>
<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>
Expand Down
8 changes: 7 additions & 1 deletion src/doc/man/generated/cargo-check.html
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,8 @@ <h3 id="cargo_check_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -174,6 +175,11 @@ <h3 id="cargo_check_compilation_options">Compilation Options</h3>
<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>
Expand Down
5 changes: 5 additions & 0 deletions src/doc/man/generated/cargo-clean.html
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,11 @@ <h3 id="cargo_clean_clean_options">Clean Options</h3>
<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>
Expand Down
8 changes: 7 additions & 1 deletion src/doc/man/generated/cargo-doc.html
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,8 @@ <h3 id="cargo_doc_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -152,6 +153,11 @@ <h3 id="cargo_doc_compilation_options">Compilation Options</h3>
<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>
Expand Down
5 changes: 5 additions & 0 deletions src/doc/man/generated/cargo-fetch.html
Original file line number Diff line number Diff line change
Expand Up @@ -50,6 +50,11 @@ <h3 id="cargo_fetch_fetch_options">Fetch options</h3>
<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>
Expand Down
23 changes: 17 additions & 6 deletions src/doc/man/generated/cargo-fix.html
Original file line number Diff line number Diff line change
Expand Up @@ -34,20 +34,25 @@ <h2 id="cargo_fix_description">DESCRIPTION</h2>
</div>
</div>
<div class="paragraph">
<p>which behaves the same as <code>cargo check --all-targets</code>. Similarly if you&#8217;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 --target x86_64-pc-windows-gnu</pre>
<pre>cargo fix --edition --features foo</pre>
</div>
</div>
<div class="paragraph">
<p>or if your crate has optional features:</p>
<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">
<pre>cargo fix --edition --no-default-features --features foo</pre>
<pre>cargo fix --edition --target x86_64-pc-windows-gnu</pre>
</div>
</div>
<div class="paragraph">
Expand Down Expand Up @@ -217,7 +222,8 @@ <h3 id="cargo_fix_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -245,6 +251,11 @@ <h3 id="cargo_fix_compilation_options">Compilation Options</h3>
<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>
Expand Down
8 changes: 7 additions & 1 deletion src/doc/man/generated/cargo-install.html
Original file line number Diff line number Diff line change
Expand Up @@ -212,7 +212,8 @@ <h3 id="cargo_install_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -240,6 +241,11 @@ <h3 id="cargo_install_compilation_options">Compilation Options</h3>
<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>
Expand Down
3 changes: 2 additions & 1 deletion src/doc/man/generated/cargo-metadata.html
Original file line number Diff line number Diff line change
Expand Up @@ -321,7 +321,8 @@ <h3 id="cargo_metadata_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down
17 changes: 16 additions & 1 deletion src/doc/man/generated/cargo-package.html
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,15 @@ <h2 id="cargo_package_description">DESCRIPTION</h2>
</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>
Expand Down Expand Up @@ -117,6 +126,11 @@ <h3 id="cargo_package_compilation_options">Compilation Options</h3>
<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>
Expand All @@ -140,7 +154,8 @@ <h3 id="cargo_package_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down
8 changes: 7 additions & 1 deletion src/doc/man/generated/cargo-publish.html
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,11 @@ <h3 id="cargo_publish_compilation_options">Compilation Options</h3>
<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>
Expand All @@ -133,7 +138,8 @@ <h3 id="cargo_publish_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down
8 changes: 7 additions & 1 deletion src/doc/man/generated/cargo-run.html
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,8 @@ <h3 id="cargo_run_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -104,6 +105,11 @@ <h3 id="cargo_run_compilation_options">Compilation Options</h3>
<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>
Expand Down
12 changes: 9 additions & 3 deletions src/doc/man/generated/cargo-rustc.html
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,8 @@ <h2 id="cargo_rustc_description">DESCRIPTION</h2>
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>
Expand Down Expand Up @@ -137,7 +137,8 @@ <h3 id="cargo_rustc_feature_selection">Feature Selection</h3>
<dd>
<p>Space or comma separated list of features to activate. These features only
apply to the current directory&#8217;s package. Features of direct dependencies
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</code> syntax.</p>
may be enabled with <code>&lt;dep-name&gt;/&lt;feature-name&gt;</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>
Expand Down Expand Up @@ -165,6 +166,11 @@ <h3 id="cargo_rustc_compilation_options">Compilation Options</h3>
<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>
Expand Down
Loading