itsscb/cargo
1
0
Fork 0
mirror of https://github.com/rust-lang/cargo.git synced 2025-09-25 11:14:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Reformat asciidoc man pages to markdown.

Browse Source
This commit is contained in:
Eric Huss 2020-08-01 09:35:24 -07:00
parent 5594bfa4bd
commit 7b7d80e84a
57 changed files with 1931 additions and 1660 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

115
src/doc/man/cargo-bench.md
View File

@ -1,27 +1,25 @@
= cargo-bench(1)
:idprefix: cargo_bench_
:doctype: manpage
:actionverb: Benchmark
:nouns: benchmarks
# cargo-bench(1)
{{*set actionverb="Benchmark"}}
{{*set nouns="benchmarks"}}
== NAME
## NAME
cargo-bench - Execute benchmarks of a package
== SYNOPSIS
## SYNOPSIS
`cargo bench [_OPTIONS_] [BENCHNAME] [-- _BENCH-OPTIONS_]`
`cargo bench` [_options_] [_benchname_] [`--` _bench-options_]
== DESCRIPTION
## DESCRIPTION
Compile and execute benchmarks.
The benchmark filtering argument `BENCHNAME` and all the arguments following
The benchmark filtering argument _benchname_ and all the arguments following
the two dashes (`--`) are passed to the benchmark binaries and thus to
_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If
you're passing arguments to both Cargo and the binary, the ones after `--` go
to the binary, the ones before go to Cargo. For details about libtest's
arguments see the output of `cargo bench \-- --help`. As an example, this will
_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If
you are passing arguments to both Cargo and the binary, the ones after `--` go
to the binary, the ones before go to Cargo. For details about libtest's
arguments see the output of `cargo bench -- --help`. As an example, this will
run only the benchmark named `foo` (and skip other similarly named benchmarks
like `foobar`):
@ -36,27 +34,24 @@ The libtest harness may be disabled by setting `harness = false` in the target
manifest settings, in which case your code will need to provide its own `main`
function to handle running benchmarks.
> **Note**: The
> link:https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html[`#[bench\]` attribute]
> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html)
> is currently unstable and only available on the
> link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel].
> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html).
> There are some packages available on
> link:https://crates.io/keywords/benchmark[crates.io] that may help with
> [crates.io](https://crates.io/keywords/benchmark) that may help with
> running benchmarks on the stable channel, such as
> link:https://crates.io/crates/criterion[Criterion].
> [Criterion](https://crates.io/crates/criterion).
== OPTIONS
## OPTIONS
=== Benchmark Options
### Benchmark Options
include::options-test.adoc[]
{{> options-test }}
=== Package Selection
{{> section-package-selection }}
include::options-packages.adoc[]
=== Target Selection
### Target Selection
When no target selection options are given, `cargo bench` will build the
following targets of the selected packages:
@ -75,19 +70,25 @@ them from being benchmarked by default. Target selection options that take a
target by name ignore the `bench` flag and will always benchmark the given
target.
include::options-targets.adoc[]
{{> options-targets }}
include::options-features.adoc[]
{{> section-features }}
=== Compilation Options
### Compilation Options
include::options-target-triple.adoc[]
{{#options}}
=== Output Options
{{> options-target-triple }}
include::options-target-dir.adoc[]
{{/options}}
=== Display Options
### Output Options
{{#options}}
{{> options-target-dir }}
{{/options}}
### Display Options
By default the Rust test harness hides output from benchmark execution to keep
results readable. Benchmark output can be recovered (e.g., for debugging) by
@ -95,33 +96,39 @@ passing `--nocapture` to the benchmark binaries:
cargo bench -- --nocapture
include::options-display.adoc[]
{{#options}}
include::options-message-format.adoc[]
{{> options-display }}
=== Manifest Options
{{> options-message-format }}
include::options-manifest-path.adoc[]
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
{{/options}}
=== Miscellaneous Options
{{> section-options-common }}
### Miscellaneous Options
The `--jobs` argument affects the building of the benchmark executable but
does not affect how many threads are used when running the benchmarks. The
Rust test harness runs benchmarks serially in a single thread.
include::options-jobs.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
== PROFILES
## PROFILES
Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
linkcargo:reference/profiles.html[the reference]
[the reference](../reference/profiles.html)
for more details.
Benchmarks are always built with the `bench` profile. Binary and lib targets
@ -130,23 +137,23 @@ are built with the `release` profiles when linked to binaries and benchmarks.
Dependencies use the `release` profile.
If you need a debug build of a benchmark, try building it with
man:cargo-build[1] which will use the `test` profile which is by default
{{man "cargo-build" 1}} which will use the `test` profile which is by default
unoptimized and includes debug information. You can then run the debug-enabled
benchmark manually.
include::section-environment.adoc[]
{{> section-environment }}
include::section-exit-status.adoc[]
{{> section-exit-status }}
== EXAMPLES
## EXAMPLES
. Build and execute all the benchmarks of the current package:
1. Build and execute all the benchmarks of the current package:
cargo bench
cargo bench
. Run only a specific benchmark within a specific benchmark target:
2. Run only a specific benchmark within a specific benchmark target:
cargo bench --bench bench_name -- modname::some_benchmark
cargo bench --bench bench_name -- modname::some_benchmark
== SEE ALSO
man:cargo[1], man:cargo-test[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-test" 1}}

111
src/doc/man/cargo-build.md
View File

@ -1,98 +1,107 @@
= cargo-build(1)
:idprefix: cargo_build_
:doctype: manpage
:actionverb: Build
# cargo-build(1)
{{*set actionverb="Build"}}
== NAME
## NAME
cargo-build - Compile the current package
== SYNOPSIS
## SYNOPSIS
`cargo build [_OPTIONS_]`
`cargo build` [_options_]
== DESCRIPTION
## DESCRIPTION
Compile local packages and all of their dependencies.
== OPTIONS
## OPTIONS
=== Package Selection
{{> section-package-selection }}
include::options-packages.adoc[]
=== Target Selection
### Target Selection
When no target selection options are given, `cargo build` will build all
binary and library targets of the selected packages. Binaries are skipped if
they have `required-features` that are missing.
include::options-targets.adoc[]
{{> options-targets }}
include::options-features.adoc[]
{{> section-features }}
=== Compilation Options
### Compilation Options
include::options-target-triple.adoc[]
{{#options}}
include::options-release.adoc[]
{{> options-target-triple }}
=== Output Options
{{> options-release }}
include::options-target-dir.adoc[]
{{/options}}
### Output Options
{{#options}}
{{> options-target-dir }}
{{#option "`--out-dir` _directory_" }}
Copy final artifacts to this directory.
*--out-dir* _DIRECTORY_::
Copy final artifacts to this directory.
+
This option is unstable and available only on the
link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel]
[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html)
and requires the `-Z unstable-options` flag to enable.
See https://github.com/rust-lang/cargo/issues/6790 for more information.
{{/option}}
=== Display Options
{{/options}}
include::options-display.adoc[]
### Display Options
include::options-message-format.adoc[]
{{#options}}
{{> options-display }}
{{> options-message-format }}
{{#option "`--build-plan`" }}
Outputs a series of JSON messages to stdout that indicate the commands to run
the build.
*--build-plan*::
Outputs a series of JSON messages to stdout that indicate the commands to
run the build.
+
This option is unstable and available only on the
link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel]
[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html)
and requires the `-Z unstable-options` flag to enable.
See https://github.com/rust-lang/cargo/issues/5579 for more information.
See <https://github.com/rust-lang/cargo/issues/5579> for more information.
{{/option}}
{{/options}}
=== Manifest Options
### Manifest Options
include::options-manifest-path.adoc[]
{{#options}}
{{> options-manifest-path }}
include::options-locked.adoc[]
{{> options-locked }}
{{/options}}
=== Common Options
{{> section-options-common }}
include::options-common.adoc[]
### Miscellaneous Options
=== Miscellaneous Options
{{#options}}
{{> options-jobs }}
{{/options}}
include::options-jobs.adoc[]
{{> section-profiles }}
include::section-profiles.adoc[]
{{> section-environment }}
include::section-environment.adoc[]
{{> section-exit-status }}
include::section-exit-status.adoc[]
## EXAMPLES
== EXAMPLES
1. Build the local package and all of its dependencies:
. Build the local package and all of its dependencies:
cargo build
cargo build
2. Build with optimizations:
. Build with optimizations:
cargo build --release
cargo build --release
== SEE ALSO
man:cargo[1], man:cargo-rustc[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-rustc" 1}}

88
src/doc/man/cargo-check.md
View File

@ -1,17 +1,15 @@
= cargo-check(1)
:idprefix: cargo_check_
:doctype: manpage
:actionverb: Check
# cargo-check(1)
{{*set actionverb="Check"}}
== NAME
## NAME
cargo-check - Check the current package
== SYNOPSIS
## SYNOPSIS
`cargo check [_OPTIONS_]`
`cargo check` [_options_]
== DESCRIPTION
## DESCRIPTION
Check a local package and all of its dependencies for errors. This will
essentially compile the packages without performing the final step of code
@ -19,69 +17,77 @@ generation, which is faster than running `cargo build`. The compiler will save
metadata files to disk so that future runs will reuse them if the source has
not been modified.
== OPTIONS
## OPTIONS
=== Package Selection
{{> section-package-selection }}
include::options-packages.adoc[]
=== Target Selection
### Target Selection
When no target selection options are given, `cargo check` will check all
binary and library targets of the selected packages. Binaries are skipped if
they have `required-features` that are missing.
include::options-targets.adoc[]
{{> options-targets }}
include::options-features.adoc[]
{{> section-features }}
=== Compilation Options
### Compilation Options
include::options-target-triple.adoc[]
{{#options}}
include::options-release.adoc[]
{{> options-target-triple }}
include::options-profile.adoc[]
{{> options-release }}
=== Output Options
{{> options-profile }}
include::options-target-dir.adoc[]
{{/options}}
=== Display Options
### Output Options
include::options-display.adoc[]
{{#options}}
{{> options-target-dir }}
{{/options}}
include::options-message-format.adoc[]
### Display Options
=== Manifest Options
{{#options}}
{{> options-display }}
include::options-manifest-path.adoc[]
{{> options-message-format }}
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
{{/options}}
=== Miscellaneous Options
{{> section-options-common }}
include::options-jobs.adoc[]
### Miscellaneous Options
include::section-profiles.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
include::section-environment.adoc[]
{{> section-profiles }}
include::section-exit-status.adoc[]
{{> section-environment }}
== EXAMPLES
{{> section-exit-status }}
. Check the local package for errors:
## EXAMPLES
cargo check
1. Check the local package for errors:
. Check all targets, including unit tests:
cargo check
cargo check --all-targets --profile=test
2. Check all targets, including unit tests:
== SEE ALSO
man:cargo[1], man:cargo-build[1]
cargo check --all-targets --profile=test
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-build" 1}}

85
src/doc/man/cargo-clean.md
View File

@ -1,76 +1,83 @@
= cargo-clean(1)
:idprefix: cargo_clean_
:doctype: manpage
:actionverb: Clean
# cargo-clean(1)
{{*set actionverb="Clean"}}
== NAME
## NAME
cargo-clean - Remove generated artifacts
== SYNOPSIS
## SYNOPSIS
`cargo clean [_OPTIONS_]`
`cargo clean` [_options_]
== DESCRIPTION
## DESCRIPTION
Remove artifacts from the target directory that Cargo has generated in the
past.
With no options, `cargo clean` will delete the entire target directory.
== OPTIONS
## OPTIONS
=== Package Selection
### Package Selection
When no packages are selected, all packages and all dependencies in the
workspace are cleaned.
*-p* _SPEC_...::
*--package* _SPEC_...::
Clean only the specified packages. This flag may be specified
multiple times. See man:cargo-pkgid[1] for the SPEC format.
{{#options}}
{{#option "`-p` _spec_..." "`--package` _spec_..." }}
Clean only the specified packages. This flag may be specified
multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format.
{{/option}}
{{/options}}
=== Clean Options
### Clean Options
*--doc*::
This option will cause `cargo clean` to remove only the `doc` directory in
the target directory.
{{#options}}
*--release*::
Clean all artifacts that were built with the `release` or `bench`
profiles.
{{#option "`--doc`" }}
This option will cause `cargo clean` to remove only the `doc` directory in
the target directory.
{{/option}}
include::options-target-dir.adoc[]
{{#option "`--release`" }}
Clean all artifacts that were built with the `release` or `bench` profiles.
{{/option}}
include::options-target-triple.adoc[]
{{> options-target-dir }}
=== Display Options
{{> options-target-triple }}
include::options-display.adoc[]
{{/options}}
=== Manifest Options
### Display Options
include::options-manifest-path.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
{{/options}}
include::section-environment.adoc[]
{{> section-options-common }}
include::section-exit-status.adoc[]
{{> section-environment }}
== EXAMPLES
{{> section-exit-status }}
. Remove the entire target directory:
## EXAMPLES
cargo clean
1. Remove the entire target directory:
. Remove only the release artifacts:
cargo clean
cargo clean --release
2. Remove only the release artifacts:
== SEE ALSO
man:cargo[1], man:cargo-build[1]
cargo clean --release
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-build" 1}}

108
src/doc/man/cargo-doc.md
View File

@ -1,41 +1,43 @@
= cargo-doc(1)
:idprefix: cargo_doc_
:doctype: manpage
:actionverb: Document
# cargo-doc(1)
{{*set actionverb="Document"}}
== NAME
## NAME
cargo-doc - Build a package's documentation
== SYNOPSIS
## SYNOPSIS
`cargo doc [_OPTIONS_]`
`cargo doc` [_options_]
== DESCRIPTION
## DESCRIPTION
Build the documentation for the local package and all dependencies. The output
is placed in `target/doc` in rustdoc's usual format.
== OPTIONS
## OPTIONS
=== Documentation Options
### Documentation Options
*--open*::
Open the docs in a browser after building them. This will use your default
browser unless you define another one in the `BROWSER` environment
variable.
{{#options}}
*--no-deps*::
Do not build documentation for dependencies.
{{#option "`--open`" }}
Open the docs in a browser after building them. This will use your default
browser unless you define another one in the `BROWSER` environment variable.
{{/option}}
*--document-private-items*::
Include non-public items in the documentation.
{{#option "`--no-deps`" }}
Do not build documentation for dependencies.
{{/option}}
=== Package Selection
{{#option "`--document-private-items`" }}
Include non-public items in the documentation.
{{/option}}
include::options-packages.adoc[]
{{/options}}
=== Target Selection
{{> section-package-selection }}
### Target Selection
When no target selection options are given, `cargo doc` will document all
binary and library targets of the selected package. The binary will be skipped
@ -46,52 +48,64 @@ The default behavior can be changed by setting `doc = false` for the target in
the manifest settings. Using target selection options will ignore the `doc`
flag and will always document the given target.
include::options-targets-lib-bin.adoc[]
{{#options}}
{{> options-targets-lib-bin }}
{{/options}}
include::options-features.adoc[]
{{> section-features }}
=== Compilation Options
### Compilation Options
include::options-target-triple.adoc[]
{{#options}}
include::options-release.adoc[]
{{> options-target-triple }}
=== Output Options
{{> options-release }}
include::options-target-dir.adoc[]
{{/options}}
=== Display Options
### Output Options
include::options-display.adoc[]
{{#options}}
{{> options-target-dir }}
{{/options}}
include::options-message-format.adoc[]
### Display Options
=== Manifest Options
{{#options}}
{{> options-display }}
include::options-manifest-path.adoc[]
{{> options-message-format }}
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
{{/options}}
=== Miscellaneous Options
{{> section-options-common }}
include::options-jobs.adoc[]
### Miscellaneous Options
include::section-profiles.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
include::section-environment.adoc[]
{{> section-profiles }}
include::section-exit-status.adoc[]
{{> section-environment }}
== EXAMPLES
{{> section-exit-status }}
. Build the local package documentation and its dependencies and output to
`target/doc`.
## EXAMPLES
cargo doc
1. Build the local package documentation and its dependencies and output to
`target/doc`.
== SEE ALSO
man:cargo[1], man:cargo-rustdoc[1], man:rustdoc[1]
cargo doc
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-rustdoc" 1}}, {{man "rustdoc" 1}}

56
src/doc/man/cargo-fetch.md
View File

@ -1,17 +1,15 @@
= cargo-fetch(1)
:idprefix: cargo_fetch_
:doctype: manpage
:actionverb: Fetch
# cargo-fetch(1)
{{*set actionverb="Fetch"}}
== NAME
## NAME
cargo-fetch - Fetch dependencies of a package from the network
== SYNOPSIS
## SYNOPSIS
`cargo fetch [_OPTIONS_]`
`cargo fetch` [_options_]
== DESCRIPTION
## DESCRIPTION
If a `Cargo.lock` file is available, this command will ensure that all of the
git dependencies and/or registry dependencies are downloaded and locally
@ -23,39 +21,43 @@ file before fetching the dependencies.
If `--target` is not specified, then all target dependencies are fetched.
See also the link:https://crates.io/crates/cargo-prefetch[cargo-prefetch]
See also the [cargo-prefetch](https://crates.io/crates/cargo-prefetch)
plugin which adds a command to download popular crates. This may be useful if
you plan to use Cargo without a network with the `--offline` flag.
== OPTIONS
## OPTIONS
=== Fetch options
### Fetch options
include::options-target-triple.adoc[]
{{#options}}
{{> options-target-triple }}
{{/options}}
=== Display Options
### Display Options
include::options-display.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
=== Manifest Options
### Manifest Options
include::options-manifest-path.adoc[]
{{#options}}
{{> options-manifest-path }}
include::options-locked.adoc[]
{{> options-locked }}
{{/options}}
=== Common Options
{{> section-options-common }}
include::options-common.adoc[]
{{> section-environment }}
include::section-environment.adoc[]
{{> section-exit-status }}
include::section-exit-status.adoc[]
## EXAMPLES
== EXAMPLES
1. Fetch all dependencies:
. Fetch all dependencies:
cargo fetch
cargo fetch
== SEE ALSO
man:cargo[1], man:cargo-update[1], man:cargo-generate-lockfile[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-update" 1}}, {{man "cargo-generate-lockfile" 1}}

140
src/doc/man/cargo-fix.md
View File

@ -1,17 +1,15 @@
= cargo-fix(1)
:idprefix: cargo_fix_
:doctype: manpage
:actionverb: Fix
# cargo-fix(1)
{{*set actionverb="Fix"}}
== NAME
## NAME
cargo-fix - Automatically fix lint warnings reported by rustc
== SYNOPSIS
## SYNOPSIS
`cargo fix [_OPTIONS_]`
`cargo fix` [_options_]
== DESCRIPTION
## DESCRIPTION
This Cargo subcommand will automatically take rustc's suggestions from
diagnostics like warnings and apply them to your source code. This is intended
@ -20,7 +18,7 @@ The `cargo fix` subcommand is also being developed for the Rust 2018 edition
to provide code the ability to easily opt-in to the new edition without having
to worry about any breakage.
Executing `cargo fix` will under the hood execute man:cargo-check[1]. Any warnings
Executing `cargo fix` will under the hood execute {{man "cargo-check" 1}}. Any warnings
applicable to your crate will be automatically fixed (if possible) and all
remaining warnings will be displayed when the check process is finished. For
example if you'd like to prepare for the 2018 edition, you can do so by
@ -43,100 +41,118 @@ pass `--target` to fix code for the given target.
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
<https://github.com/rust-lang/cargo>
== OPTIONS
## OPTIONS
=== Fix options
### Fix options
*--broken-code*::
Fix code even if it already has compiler errors. This is useful if `cargo
fix` fails to apply the changes. It will apply the changes and leave the
broken code in the working directory for you to inspect and manually fix.
{{#options}}
*--edition*::
Apply changes that will update the code to the latest edition. This will
not update the edition in the `Cargo.toml` manifest, which must be updated
manually.
{{#option "`--broken-code`" }}
Fix code even if it already has compiler errors. This is useful if `cargo fix`
fails to apply the changes. It will apply the changes and leave the broken
code in the working directory for you to inspect and manually fix.
{{/option}}
*--edition-idioms*::
Apply suggestions that will update code to the preferred style for the
current edition.
{{#option "`--edition`" }}
Apply changes that will update the code to the latest edition. This will not
update the edition in the `Cargo.toml` manifest, which must be updated
manually.
{{/option}}
*--allow-no-vcs*::
Fix code even if a VCS was not detected.
{{#option "`--edition-idioms`" }}
Apply suggestions that will update code to the preferred style for the current
edition.
{{/option}}
*--allow-dirty*::
Fix code even if the working directory has changes.
{{#option "`--allow-no-vcs`" }}
Fix code even if a VCS was not detected.
{{/option}}
*--allow-staged*::
Fix code even if the working directory has staged changes.
{{#option "`--allow-dirty`" }}
Fix code even if the working directory has changes.
{{/option}}
=== Package Selection
{{#option "`--allow-staged`" }}
Fix code even if the working directory has staged changes.
{{/option}}
include::options-packages.adoc[]
{{/options}}
=== Target Selection
{{> section-package-selection }}
### Target Selection
When no target selection options are given, `cargo fix` will fix all targets
(`--all-targets` implied). Binaries are skipped if they have
`required-features` that are missing.
include::options-targets.adoc[]
{{> options-targets }}
include::options-features.adoc[]
{{> section-features }}
=== Compilation Options
### Compilation Options
include::options-target-triple.adoc[]
{{#options}}
include::options-release.adoc[]
{{> options-target-triple }}
include::options-profile.adoc[]
{{> options-release }}
=== Output Options
{{> options-profile }}
include::options-target-dir.adoc[]
{{/options}}
=== Display Options
### Output Options
include::options-display.adoc[]
{{#options}}
{{> options-target-dir }}
{{/options}}
include::options-message-format.adoc[]
### Display Options
=== Manifest Options
{{#options}}
{{> options-display }}
include::options-manifest-path.adoc[]
{{> options-message-format }}
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
{{/options}}
=== Miscellaneous Options
{{> section-options-common }}
include::options-jobs.adoc[]
### Miscellaneous Options
include::section-profiles.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
include::section-environment.adoc[]
{{> section-profiles }}
include::section-exit-status.adoc[]
{{> section-environment }}
== EXAMPLES
{{> section-exit-status }}
. Apply compiler suggestions to the local package:
## EXAMPLES
cargo fix
1. Apply compiler suggestions to the local package:
. Convert a 2015 edition to 2018:
cargo fix
cargo fix --edition
2. Convert a 2015 edition to 2018:
. Apply suggested idioms for the current edition:
cargo fix --edition
cargo fix --edition-idioms
3. Apply suggested idioms for the current edition:
== SEE ALSO
man:cargo[1], man:cargo-check[1]
cargo fix --edition-idioms
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-check" 1}}

48
src/doc/man/cargo-generate-lockfile.md
View File

@ -1,49 +1,49 @@
= cargo-generate-lockfile(1)
:idprefix: cargo_generate-lockfile_
:doctype: manpage
# cargo-generate-lockfile(1)
== NAME
## NAME
cargo-generate-lockfile - Generate the lockfile for a package
== SYNOPSIS
## SYNOPSIS
`cargo generate-lockfile [_OPTIONS_]`
`cargo generate-lockfile` [_options_]
== DESCRIPTION
## DESCRIPTION
This command will create the `Cargo.lock` lockfile for the current package or
workspace. If the lockfile already exists, it will be rebuilt if there are any
manifest changes or dependency updates.
See also man:cargo-update[1] which is also capable of creating a `Cargo.lock`
See also {{man "cargo-update" 1}} which is also capable of creating a `Cargo.lock`
lockfile and has more options for controlling update behavior.
== OPTIONS
## OPTIONS
=== Display Options
### Display Options
include::options-display.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
=== Manifest Options
### Manifest Options
include::options-manifest-path.adoc[]
{{#options}}
{{> options-manifest-path }}
include::options-locked.adoc[]
{{> options-locked }}
{{/options}}
=== Common Options
{{> section-options-common }}
include::options-common.adoc[]
{{> section-environment }}
include::section-environment.adoc[]
{{> section-exit-status }}
include::section-exit-status.adoc[]
## EXAMPLES
== EXAMPLES
1. Create or update the lockfile for the current package or workspace:
. Create or update the lockfile for the current package or workspace:
cargo generate-lockfile
cargo generate-lockfile
== SEE ALSO
man:cargo[1], man:cargo-update[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-update" 1}}

26
src/doc/man/cargo-help.md
View File

@ -1,28 +1,26 @@
= cargo-help(1)
:idprefix: cargo_help_
:doctype: manpage
# cargo-help(1)
== NAME
## NAME
cargo-help - Get help for a Cargo command
== SYNOPSIS
## SYNOPSIS
`cargo help [_SUBCOMMAND_]`
`cargo help` [_subcommand_]
== DESCRIPTION
## DESCRIPTION
Prints a help message for the given command.
== EXAMPLES
## EXAMPLES
. Get help for a command:
1. Get help for a command:
cargo help build
cargo help build
. Help is also available with the `--help` flag:
2. Help is also available with the `--help` flag:
cargo build --help
cargo build --help
== SEE ALSO
man:cargo[1]
## SEE ALSO
{{man "cargo" 1}}

46
src/doc/man/cargo-init.md
View File

@ -1,16 +1,14 @@
= cargo-init(1)
:idprefix: cargo_init_
:doctype: manpage
# cargo-init(1)
== NAME
## NAME
cargo-init - Create a new Cargo package in an existing directory
== SYNOPSIS
## SYNOPSIS
`cargo init [_OPTIONS_] [_PATH_]`
`cargo init` [_options_] [_path_]
== DESCRIPTION
## DESCRIPTION
This command will create a new Cargo manifest in the current directory. Give a
path as an argument to create in the given directory.
@ -22,34 +20,34 @@ will be used. If not, then a sample `src/main.rs` file will be created, or
If the directory is not already in a VCS repository, then a new repository
is created (see `--vcs` below).
include::description-new-authors.adoc[]
{{> description-new-authors }}
See man:cargo-new[1] for a similar command which will create a new package in
See {{man "cargo-new" 1}} for a similar command which will create a new package in
a new directory.
== OPTIONS
## OPTIONS
=== Init Options
### Init Options
include::options-new.adoc[]
{{> options-new }}
=== Display Options
### Display Options
include::options-display.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
=== Common Options
{{> section-options-common }}
include::options-common.adoc[]
{{> section-environment }}
include::section-environment.adoc[]
{{> section-exit-status }}
include::section-exit-status.adoc[]
## EXAMPLES
== EXAMPLES
1. Create a binary Cargo package in the current directory:
. Create a binary Cargo package in the current directory:
cargo init
cargo init
== SEE ALSO
man:cargo[1], man:cargo-new[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-new" 1}}

197
src/doc/man/cargo-install.md
View File

@ -1,33 +1,30 @@
= cargo-install(1)
:idprefix: cargo_install_
:doctype: manpage
:actionverb: Install
# cargo-install(1)
{{*set actionverb="Install"}}
== NAME
## NAME
cargo-install - Build and install a Rust binary
== SYNOPSIS
## SYNOPSIS
[%hardbreaks]
`cargo install [_OPTIONS_] _CRATE_...`
`cargo install [_OPTIONS_] --path _PATH_`
`cargo install [_OPTIONS_] --git _URL_ [_CRATE_...]`
`cargo install [_OPTIONS_] --list`
`cargo install` [_options_] _crate_...\
`cargo install` [_options_] `--path` _path_\
`cargo install` [_options_] `--git` _url_ [_crate_...]\
`cargo install` [_options_] `--list`
== DESCRIPTION
## DESCRIPTION
This command manages Cargo's local set of installed binary crates. Only
packages which have executable `\[[bin]]` or `\[[example]]` targets can be
packages which have executable `[[bin]]` or `[[example]]` targets can be
installed, and all executables are installed into the installation root's
`bin` folder.
include::description-install-root.adoc[]
{{> description-install-root }}
There are multiple sources from which a crate can be installed. The default
location is crates.io but the `--git`, `--path`, and `--registry` flags can
change this source. If the source contains more than one package (such as
crates.io or a git repository with multiple crates) the _CRATE_ argument is
crates.io or a git repository with multiple crates) the _crate_ argument is
required to indicate which crate should be installed.
Crates from crates.io can optionally specify the version they wish to install
@ -71,116 +68,140 @@ not start publishing `Cargo.lock` files until version 1.37, which means
packages published with prior versions will not have a `Cargo.lock` file
available.
== OPTIONS
## OPTIONS
=== Install Options
### Install Options
*--vers* _VERSION_::
*--version* _VERSION_::
Specify a version to install. This may be a
linkcargo:reference/specifying-dependencies.md[version requirement], like
`~1.2`, to have Cargo select the newest version from the given
requirement. If the version does not have a requirement operator (such as
`^` or `~`), then it must be in the form _MAJOR.MINOR.PATCH_, and will
install exactly that version; it is *not* treated as a caret requirement
like Cargo dependencies are.
{{#options}}
*--git* _URL_::
Git URL to install the specified crate from.
{{#option "`--vers` _version_" "`--version` _version_" }}
Specify a version to install. This may be a [version
requirement](../reference/specifying-dependencies.md), like `~1.2`, to have Cargo
select the newest version from the given requirement. If the version does not
have a requirement operator (such as `^` or `~`), then it must be in the form
_MAJOR.MINOR.PATCH_, and will install exactly that version; it is *not*
treated as a caret requirement like Cargo dependencies are.
{{/option}}
*--branch* _BRANCH_::
Branch to use when installing from git.
{{#option "`--git` _url_" }}
Git URL to install the specified crate from.
{{/option}}
*--tag* _TAG_::
Tag to use when installing from git.
{{#option "`--branch` _branch_" }}
Branch to use when installing from git.
{{/option}}
*--rev* _SHA_::
Specific commit to use when installing from git.
{{#option "`--tag` _tag_" }}
Tag to use when installing from git.
{{/option}}
*--path* _PATH_::
Filesystem path to local crate to install.
{{#option "`--rev` _sha_" }}
Specific commit to use when installing from git.
{{/option}}
*--list*::
List all installed packages and their versions.
{{#option "`--path` _path_" }}
Filesystem path to local crate to install.
{{/option}}
*-f*::
*--force*::
Force overwriting existing crates or binaries. This can be used if a
package has installed a binary with the same name as another package. This
is also useful if something has changed on the system that you want to
rebuild with, such as a newer version of `rustc`.
{{#option "`--list`" }}
List all installed packages and their versions.
{{/option}}
*--no-track*::
By default, Cargo keeps track of the installed packages with a metadata
file stored in the installation root directory. This flag tells Cargo not
to use or create that file. With this flag, Cargo will refuse to overwrite
any existing files unless the `--force` flag is used. This also disables
Cargo's ability to protect against multiple concurrent invocations of
Cargo installing at the same time.
{{#option "`-f`" "`--force`" }}
Force overwriting existing crates or binaries. This can be used if a package
has installed a binary with the same name as another package. This is also
useful if something has changed on the system that you want to rebuild with,
such as a newer version of `rustc`.
{{/option}}
*--bin* _NAME_...::
Install only the specified binary.
{{#option "`--no-track`" }}
By default, Cargo keeps track of the installed packages with a metadata file
stored in the installation root directory. This flag tells Cargo not to use or
create that file. With this flag, Cargo will refuse to overwrite any existing
files unless the `--force` flag is used. This also disables Cargo's ability to
protect against multiple concurrent invocations of Cargo installing at the
same time.
{{/option}}
*--bins*::
Install all binaries.
{{#option "`--bin` _name_..." }}
Install only the specified binary.
{{/option}}
*--example* _NAME_...::
Install only the specified example.
{{#option "`--bins`" }}
Install all binaries.
{{/option}}
*--examples*::
Install all examples.
{{#option "`--example` _name_..." }}
Install only the specified example.
{{/option}}
*--root* _DIR_::
Directory to install packages into.
{{#option "`--examples`" }}
Install all examples.
{{/option}}
include::options-registry.adoc[]
{{#option "`--root` _dir_" }}
Directory to install packages into.
{{/option}}
include::options-index.adoc[]
{{> options-registry }}
include::options-features.adoc[]
{{> options-index }}
=== Compilation Options
{{/options}}
include::options-target-triple.adoc[]
{{> section-features }}
include::options-target-dir.adoc[]
### Compilation Options
*--debug*::
Build with the `dev` profile instead the `release` profile.
{{#options}}
=== Manifest Options
{{> options-target-triple }}
include::options-locked.adoc[]
{{> options-target-dir }}
=== Miscellaneous Options
{{#option "`--debug`" }}
Build with the `dev` profile instead the `release` profile.
{{/option}}
include::options-jobs.adoc[]
{{/options}}
=== Display Options
### Manifest Options
include::options-display.adoc[]
{{#options}}
{{> options-locked }}
{{/options}}
=== Common Options
### Miscellaneous Options
include::options-common.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
include::section-environment.adoc[]
### Display Options
include::section-exit-status.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
== EXAMPLES
{{> section-options-common }}
. Install or upgrade a package from crates.io:
{{> section-environment }}
cargo install ripgrep
{{> section-exit-status }}
. Install or reinstall the package in the current directory:
## EXAMPLES
cargo install --path .
1. Install or upgrade a package from crates.io:
. View the list of installed packages:
cargo install ripgrep
cargo install --list
2. Install or reinstall the package in the current directory:
== SEE ALSO
man:cargo[1], man:cargo-uninstall[1], man:cargo-search[1], man:cargo-publish[1]
cargo install --path .
3. View the list of installed packages:
cargo install --list
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-uninstall" 1}}, {{man "cargo-search" 1}}, {{man "cargo-publish" 1}}

46
src/doc/man/cargo-locate-project.md
View File

@ -1,46 +1,46 @@
= cargo-locate-project(1)
:idprefix: cargo_locate-project_
:doctype: manpage
# cargo-locate-project(1)
== NAME
## NAME
cargo-locate-project - Print a JSON representation of a Cargo.toml file's location
== SYNOPSIS
## SYNOPSIS
`cargo locate-project [_OPTIONS_]`
`cargo locate-project` [_options_]
== DESCRIPTION
## DESCRIPTION
This command will print a JSON object to stdout with the full path to the
`Cargo.toml` manifest.
See also man:cargo-metadata[1] which is capable of returning the path to a
See also {{man "cargo-metadata" 1}} which is capable of returning the path to a
workspace root.
== OPTIONS
## OPTIONS
=== Display Options
### Display Options
include::options-display.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
=== Manifest Options
### Manifest Options
include::options-manifest-path.adoc[]
{{#options}}
{{> options-manifest-path }}
{{/options}}
=== Common Options
{{> section-options-common }}
include::options-common.adoc[]
{{> section-environment }}
include::section-environment.adoc[]
{{> section-exit-status }}
include::section-exit-status.adoc[]
## EXAMPLES
== EXAMPLES
1. Display the path to the manifest based on the current directory:
. Display the path to the manifest based on the current directory:
cargo locate-project
cargo locate-project
== SEE ALSO
man:cargo[1], man:cargo-metadata[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-metadata" 1}}

50
src/doc/man/cargo-login.md
View File

@ -1,51 +1,51 @@
= cargo-login(1)
:idprefix: cargo_login_
:doctype: manpage
# cargo-login(1)
== NAME
## NAME
cargo-login - Save an API token from the registry locally
== SYNOPSIS
## SYNOPSIS
`cargo login [_OPTIONS_] [_TOKEN_]`
`cargo login` [_options_] [_token_]
== DESCRIPTION
## DESCRIPTION
This command will save the API token to disk so that commands that require
authentication, such as man:cargo-publish[1], will be automatically
authentication, such as {{man "cargo-publish" 1}}, will be automatically
authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME`
defaults to `.cargo` in your home directory.
If the _TOKEN_ argument is not specified, it will be read from stdin.
If the _token_ argument is not specified, it will be read from stdin.
The API token for crates.io may be retrieved from https://crates.io/me.
The API token for crates.io may be retrieved from <https://crates.io/me>.
Take care to keep the token secret, it should not be shared with anyone else.
== OPTIONS
## OPTIONS
=== Login Options
### Login Options
include::options-registry.adoc[]
{{#options}}
{{> options-registry }}
{{/options}}
=== Display Options
### Display Options
include::options-display.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
=== Common Options
{{> section-options-common }}
include::options-common.adoc[]
{{> section-environment }}
include::section-environment.adoc[]
{{> section-exit-status }}
include::section-exit-status.adoc[]
## EXAMPLES
== EXAMPLES
1. Save the API token to disk:
. Save the API token to disk:
cargo login
cargo login
== SEE ALSO
man:cargo[1], man:cargo-publish[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-publish" 1}}

84
src/doc/man/cargo-metadata.md
View File

@ -1,17 +1,15 @@
= cargo-metadata(1)
:idprefix: cargo_metadata_
:doctype: manpage
# cargo-metadata(1)
:source-highlighter: highlightjs
== NAME
## NAME
cargo-metadata - Machine-readable metadata about the current package
== SYNOPSIS
## SYNOPSIS
`cargo metadata [_OPTIONS_]`
`cargo metadata` [_options_]
== DESCRIPTION
## DESCRIPTION
Output JSON to stdout containing information about the workspace members and
resolved dependencies of the current package.
@ -19,15 +17,14 @@ resolved dependencies of the current package.
It is recommended to include the `--format-version` flag to future-proof
your code to ensure the output is in the format you are expecting.
See the link:https://crates.io/crates/cargo_metadata[cargo_metadata crate]
See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata)
for a Rust API for reading the metadata.
== OUTPUT FORMAT
## OUTPUT FORMAT
The output has the following format:
[source,javascript]
----
```javascript
{
/* Array of all packages in the workspace.
It also includes all feature-enabled dependencies unless --no-deps is used.
@ -281,53 +278,62 @@ The output has the following format:
}
}
}
----
````
== OPTIONS
## OPTIONS
=== Output Options
### Output Options
*--no-deps*::
Output information only about the workspace members and don't fetch
dependencies.
{{#options}}
*--format-version* _VERSION_::
Specify the version of the output format to use. Currently `1` is the only
possible value.
{{#option "`--no-deps`" }}
Output information only about the workspace members and don't fetch
dependencies.
{{/option}}
{{#option "`--format-version` _version_" }}
Specify the version of the output format to use. Currently `1` is the only
possible value.
{{/option}}
{{#option "`--filter-platform` _triple_" }}
This filters the `resolve` output to only include dependencies for the
given target triple. Without this flag, the resolve includes all targets.
*--filter-platform* _TRIPLE_::
This filters the `resolve` output to only include dependencies for the
given target triple. Without this flag, the resolve includes all targets.
+
Note that the dependencies listed in the "packages" array still includes all
dependencies. Each package definition is intended to be an unaltered
reproduction of the information within `Cargo.toml`.
{{/option}}
include::options-features.adoc[]
{{/options}}
=== Display Options
{{> section-features }}
include::options-display.adoc[]
### Display Options
=== Manifest Options
{{#options}}
{{> options-display }}
{{/options}}
include::options-manifest-path.adoc[]
### Manifest Options
include::options-locked.adoc[]
{{#options}}
{{> options-manifest-path }}
=== Common Options
{{> options-locked }}
{{/options}}
include::options-common.adoc[]
{{> section-options-common }}
include::section-environment.adoc[]
{{> section-environment }}
include::section-exit-status.adoc[]
{{> section-exit-status }}
== EXAMPLES
## EXAMPLES
. Output JSON about the current package:
1. Output JSON about the current package:
cargo metadata --format-version=1
cargo metadata --format-version=1
== SEE ALSO
man:cargo[1]
## SEE ALSO
{{man "cargo" 1}}

46
src/doc/man/cargo-new.md
View File

@ -1,50 +1,48 @@
= cargo-new(1)
:idprefix: cargo_new_
:doctype: manpage
# cargo-new(1)
== NAME
## NAME
cargo-new - Create a new Cargo package
== SYNOPSIS
## SYNOPSIS
`cargo new [_OPTIONS_] _PATH_`
`cargo new` [_options_] _path_
== DESCRIPTION
## DESCRIPTION
This command will create a new Cargo package in the given directory. This
includes a simple template with a `Cargo.toml` manifest, sample source file,
and a VCS ignore file. If the directory is not already in a VCS repository,
then a new repository is created (see `--vcs` below).
include::description-new-authors.adoc[]
{{> description-new-authors }}
See man:cargo-init[1] for a similar command which will create a new manifest
See {{man "cargo-init" 1}} for a similar command which will create a new manifest
in an existing directory.
== OPTIONS
## OPTIONS
=== New Options
### New Options
include::options-new.adoc[]
{{> options-new }}
=== Display Options
### Display Options
include::options-display.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
=== Common Options
{{> section-options-common }}
include::options-common.adoc[]
{{> section-environment }}
include::section-environment.adoc[]
{{> section-exit-status }}
include::section-exit-status.adoc[]
## EXAMPLES
== EXAMPLES
1. Create a binary Cargo package in the given directory:
. Create a binary Cargo package in the given directory:
cargo new foo
cargo new foo
== SEE ALSO
man:cargo[1], man:cargo-init[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-init" 1}}

83
src/doc/man/cargo-owner.md
View File

@ -1,80 +1,81 @@
= cargo-owner(1)
:idprefix: cargo_owner_
:doctype: manpage
# cargo-owner(1)
== NAME
## NAME
cargo-owner - Manage the owners of a crate on the registry
== SYNOPSIS
## SYNOPSIS
[%hardbreaks]
`cargo owner [_OPTIONS_] --add _LOGIN_ [_CRATE_]`
`cargo owner [_OPTIONS_] --remove _LOGIN_ [_CRATE_]`
`cargo owner [_OPTIONS_] --list [_CRATE_]`
`cargo owner` [_options_] `--add` _login_ [_crate_]\
`cargo owner` [_options_] `--remove` _login_ [_crate_]\
`cargo owner` [_options_] `--list` [_crate_]
== DESCRIPTION
## DESCRIPTION
This command will modify the owners for a crate on the registry. Owners of a
crate can upload new versions and yank old versions. Non-team owners can also
modify the set of owners, so take care!
This command requires you to be authenticated with either the `--token` option
or using man:cargo-login[1].
or using {{man "cargo-login" 1}}.
If the crate name is not specified, it will use the package name from the
current directory.
See linkcargo:reference/publishing.html#cargo-owner[the reference] for more
See [the reference](../reference/publishing.html#cargo-owner) for more
information about owners and publishing.
== OPTIONS
## OPTIONS
=== Owner Options
### Owner Options
*-a*::
*--add* _LOGIN_...::
Invite the given user or team as an owner.
{{#options}}
*-r*::
*--remove* _LOGIN_...::
Remove the given user or team as an owner.
{{#option "`-a`" "`--add` _login_..." }}
Invite the given user or team as an owner.
{{/option}}
*-l*::
*--list*::
List owners of a crate.
{{#option "`-r`" "`--remove` _login_..." }}
Remove the given user or team as an owner.
{{/option}}
include::options-token.adoc[]
{{#option "`-l`" "`--list`" }}
List owners of a crate.
{{/option}}
include::options-index.adoc[]
{{> options-token }}
include::options-registry.adoc[]
{{> options-index }}
=== Display Options
{{> options-registry }}
include::options-display.adoc[]
{{/options}}
=== Common Options
### Display Options
include::options-common.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
include::section-environment.adoc[]
{{> section-options-common }}
include::section-exit-status.adoc[]
{{> section-environment }}
== EXAMPLES
{{> section-exit-status }}
. List owners of a package:
## EXAMPLES
cargo owner --list foo
1. List owners of a package:
. Invite an owner to a package:
cargo owner --list foo
cargo owner --add username foo
2. Invite an owner to a package:
. Remove an owner from a package:
cargo owner --add username foo
cargo owner --remove username foo
3. Remove an owner from a package:
== SEE ALSO
man:cargo[1], man:cargo-login[1], man:cargo-publish[1]
cargo owner --remove username foo
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-login" 1}}, {{man "cargo-publish" 1}}

107
src/doc/man/cargo-package.md
View File

@ -1,102 +1,117 @@
= cargo-package(1)
:idprefix: cargo_package_
:doctype: manpage
:actionverb: Package
# cargo-package(1)
{{*set actionverb="Package"}}
== NAME
## NAME
cargo-package - Assemble the local package into a distributable tarball
== SYNOPSIS
## SYNOPSIS
`cargo package [_OPTIONS_]`
`cargo package` [_options_]
== DESCRIPTION
## DESCRIPTION
This command will create a distributable, compressed `.crate` file with the
source code of the package in the current directory. The resulting file will
be stored in the `target/package` directory. This performs the following
steps:
. Load and check the current workspace, performing some basic checks.
1. Load and check the current workspace, performing some basic checks.
- Path dependencies are not allowed unless they have a version key. Cargo
will ignore the path key for dependencies in published packages.
`dev-dependencies` do not have this restriction.
. Create the compressed `.crate` file.
2. Create the compressed `.crate` file.
- The original `Cargo.toml` file is rewritten and normalized.
- `[patch]`, `[replace]`, and `[workspace]` sections are removed from the
manifest.
- `Cargo.lock` is automatically included if the package contains an
executable binary or example target. man:cargo-install[1] will use the
executable binary or example target. {{man "cargo-install" 1}} will use the
packaged lock file if the `--locked` flag is used.
- A `.cargo_vcs_info.json` file is included that contains information
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.
3. 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.
4. Check that build scripts did not modify any source files.
The list of files included can be controlled with the `include` and `exclude`
fields in the manifest.
See linkcargo:reference/publishing.html[the reference] for more details about
See [the reference](../reference/publishing.html) for more details about
packaging and publishing.
== OPTIONS
## OPTIONS
=== Package Options
### Package Options
*-l*::
*--list*::
Print files included in a package without making one.
{{#options}}
*--no-verify*::
Don't verify the contents by building them.
{{#option "`-l`" "`--list`" }}
Print files included in a package without making one.
{{/option}}
*--no-metadata*::
Ignore warnings about a lack of human-usable metadata (such as the
description or the license).
{{#option "`--no-verify`" }}
Don't verify the contents by building them.
{{/option}}
*--allow-dirty*::
Allow working directories with uncommitted VCS changes to be packaged.
{{#option "`--no-metadata`" }}
Ignore warnings about a lack of human-usable metadata (such as the description
or the license).
{{/option}}
=== Compilation Options
{{#option "`--allow-dirty`" }}
Allow working directories with uncommitted VCS changes to be packaged.
{{/option}}
include::options-target-triple.adoc[]
{{/options}}
include::options-target-dir.adoc[]
### Compilation Options
include::options-features.adoc[]
{{#options}}
=== Manifest Options
{{> options-target-triple }}
include::options-manifest-path.adoc[]
{{> options-target-dir }}
include::options-locked.adoc[]
{{/options}}
=== Miscellaneous Options
{{> section-features }}
include::options-jobs.adoc[]
### Manifest Options
=== Display Options
{{#options}}
include::options-display.adoc[]
{{> options-manifest-path }}
=== Common Options
{{> options-locked }}
include::options-common.adoc[]
{{/options}}
include::section-environment.adoc[]
### Miscellaneous Options
include::section-exit-status.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
== EXAMPLES
### Display Options
. Create a compressed `.crate` file of the current package:
{{#options}}
{{> options-display }}
{{/options}}
cargo package
{{> section-options-common }}
== SEE ALSO
man:cargo[1], man:cargo-publish[1]
{{> section-environment }}
{{> section-exit-status }}
## EXAMPLES
1. Create a compressed `.crate` file of the current package:
cargo package
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-publish" 1}}

99
src/doc/man/cargo-pkgid.md
View File

@ -1,21 +1,19 @@
= cargo-pkgid(1)
:idprefix: cargo_pkgid_
:doctype: manpage
# cargo-pkgid(1)
== NAME
## NAME
cargo-pkgid - Print a fully qualified package specification
== SYNOPSIS
## SYNOPSIS
`cargo pkgid [_OPTIONS_] [_SPEC_]`
`cargo pkgid` [_options_] [_spec_]
== DESCRIPTION
## DESCRIPTION
Given a _SPEC_ argument, print out the fully qualified package ID specifier
Given a _spec_ argument, print out the fully qualified package ID specifier
for a package or dependency in the current workspace. This command will
generate an error if _SPEC_ is ambiguous as to which package it refers to in
the dependency graph. If no _SPEC_ is given, then the specifier for the local
generate an error if _spec_ is ambiguous as to which package it refers to in
the dependency graph. If no _spec_ is given, then the specifier for the local
package is printed.
This command requires that a lockfile is available and dependencies have been
@ -23,72 +21,65 @@ fetched.
A package specifier consists of a name, version, and source URL. You are
allowed to use partial specifiers to succinctly match a specific package as
long as it matches only one package. The format of a _SPEC_ can be one of the
long as it matches only one package. The format of a _spec_ can be one of the
following:
[%autowidth]
.SPEC Query Format
|===
|SPEC Structure |Example SPEC
SPEC Structure | Example SPEC
---------------------------|--------------
_name_ | `bitflags`
_name_`:`_version_ | `bitflags:1.0.4`
_url_ | `https://github.com/rust-lang/cargo`
_url_`#`_version_ | `https://github.com/rust-lang/cargo#0.33.0`
_url_`#`_name_ | `https://github.com/rust-lang/crates.io-index#bitflags`
_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io:0.21.0`
|__NAME__
|`bitflags`
## OPTIONS
|__NAME__``:``__VERSION__
|`bitflags:1.0.4`
### Package Selection
|__URL__
|`https://github.com/rust-lang/cargo`
{{#options}}
|__URL__``#``__VERSION__
|`https://github.com/rust-lang/cargo#0.33.0`
{{#option "`-p` _spec_" "`--package` _spec_" }}
Get the package ID for the given package instead of the current package.
{{/option}}
|__URL__``#``__NAME__
|`https://github.com/rust-lang/crates.io-index#bitflags`
{{/options}}
|__URL__``#``__NAME__``:``__VERSION__
|`https://github.com/rust-lang/cargo#crates-io:0.21.0`
|===
### Display Options
== OPTIONS
{{#options}}
{{> options-display }}
{{/options}}
=== Package Selection
### Manifest Options
*-p* _SPEC_::
*--package* _SPEC_::
Get the package ID for the given package instead of the current package.
{{#options}}
=== Display Options
{{> options-manifest-path }}
include::options-display.adoc[]
{{> options-locked }}
=== Manifest Options
{{/options}}
include::options-manifest-path.adoc[]
{{> section-options-common }}
include::options-locked.adoc[]
{{> section-environment }}
=== Common Options
{{> section-exit-status }}
include::options-common.adoc[]
## EXAMPLES
include::section-environment.adoc[]
1. Retrieve package specification for `foo` package:
include::section-exit-status.adoc[]
cargo pkgid foo
== EXAMPLES
2. Retrieve package specification for version 1.0.0 of `foo`:
. Retrieve package specification for `foo` package:
cargo pkgid foo:1.0.0
cargo pkgid foo
3. Retrieve package specification for `foo` from crates.io:
. Retrieve package specification for version 1.0.0 of `foo`:
cargo pkgid https://github.com/rust-lang/crates.io-index#foo
cargo pkgid foo:1.0.0
. Retrieve package specification for `foo` from crates.io:
cargo pkgid https://github.com/rust-lang/crates.io-index#foo
== SEE ALSO
man:cargo[1], man:cargo-generate-lockfile[1], man:cargo-metadata[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}}

111
src/doc/man/cargo-publish.md
View File

@ -1,90 +1,105 @@
= cargo-publish(1)
:idprefix: cargo_publish_
:doctype: manpage
:actionverb: Publish
# cargo-publish(1)
{{*set actionverb="Publish"}}
== NAME
## NAME
cargo-publish - Upload a package to the registry
== SYNOPSIS
## SYNOPSIS
`cargo publish [_OPTIONS_]`
`cargo publish` [_options_]
== DESCRIPTION
## DESCRIPTION
This command will create a distributable, compressed `.crate` file with the
source code of the package in the current directory and upload it to a
registry. The default registry is https://crates.io. This performs the
registry. The default registry is <https://crates.io>. This performs the
following steps:
. Performs a few checks, including:
- Checks the `package.publish` key in the manifest for restrictions on which
registries you are allowed to publish to.
. Create a `.crate` file by following the steps in man:cargo-package[1].
. Upload the crate to the registry. Note that the server will perform
additional checks on the crate.
1. Performs a few checks, including:
- Checks the `package.publish` key in the manifest for restrictions on
which registries you are allowed to publish to.
2. Create a `.crate` file by following the steps in {{man "cargo-package" 1}}.
3. Upload the crate to the registry. Note that the server will perform
additional checks on the crate.
This command requires you to be authenticated with either the `--token` option
or using man:cargo-login[1].
or using {{man "cargo-login" 1}}.
See linkcargo:reference/publishing.html[the reference] for more details about
See [the reference](../reference/publishing.html) for more details about
packaging and publishing.
== OPTIONS
## OPTIONS
=== Publish Options
### Publish Options
*--dry-run*::
Perform all checks without uploading.
{{#options}}
include::options-token.adoc[]
{{#option "`--dry-run`" }}
Perform all checks without uploading.
{{/option}}
*--no-verify*::
Don't verify the contents by building them.
{{> options-token }}
*--allow-dirty*::
Allow working directories with uncommitted VCS changes to be packaged.
{{#option "`--no-verify`" }}
Don't verify the contents by building them.
{{/option}}
include::options-index.adoc[]
{{#option "`--allow-dirty`" }}
Allow working directories with uncommitted VCS changes to be packaged.
{{/option}}
include::options-registry.adoc[]
{{> options-index }}
=== Compilation Options
{{> options-registry }}
include::options-target-triple.adoc[]
{{/options}}
include::options-target-dir.adoc[]
### Compilation Options
include::options-features.adoc[]
{{#options}}
=== Manifest Options
{{> options-target-triple }}
include::options-manifest-path.adoc[]
{{> options-target-dir }}
include::options-locked.adoc[]
{{/options}}
=== Miscellaneous Options
{{> section-features }}
include::options-jobs.adoc[]
### Manifest Options
=== Display Options
{{#options}}
include::options-display.adoc[]
{{> options-manifest-path }}
=== Common Options
{{> options-locked }}
include::options-common.adoc[]
{{/options}}
include::section-environment.adoc[]
### Miscellaneous Options
include::section-exit-status.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
== EXAMPLES
### Display Options
. Publish the current package:
{{#options}}
{{> options-display }}
{{/options}}
cargo publish
{{> section-options-common }}
== SEE ALSO
man:cargo[1], man:cargo-package[1], man:cargo-login[1]
{{> section-environment }}
{{> section-exit-status }}
## EXAMPLES
1. Publish the current package:
cargo publish
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-package" 1}}, {{man "cargo-login" 1}}

102
src/doc/man/cargo-run.md
View File

@ -1,17 +1,15 @@
= cargo-run(1)
:idprefix: cargo_run_
:doctype: manpage
:actionverb: Run
# cargo-run(1)
{{*set actionverb="Run"}}
== NAME
## NAME
cargo-run - Run the current package
== SYNOPSIS
## SYNOPSIS
`cargo run [_OPTIONS_] [-- _ARGS_]`
`cargo run` [_options_] [`--` _args_]
== DESCRIPTION
## DESCRIPTION
Run a binary or example of the local package.
@ -19,72 +17,90 @@ All the arguments following the two dashes (`--`) are passed to the binary to
run. If you're passing arguments to both Cargo and the binary, the ones after
`--` go to the binary, the ones before go to Cargo.
== OPTIONS
## OPTIONS
=== Package Selection
{{> section-options-package }}
include::options-package.adoc[]
=== Target Selection
### Target Selection
When no target selection options are given, `cargo run` will run the binary
target. If there are multiple binary targets, you must pass a target flag to
choose one. Or, the `default-run` field may be specified in the `[package]`
section of `Cargo.toml` to choose the name of the binary to run by default.
*--bin* _NAME_::
Run the specified binary.
{{#options}}
*--example* _NAME_::
Run the specified example.
{{#option "`--bin` _name_" }}
Run the specified binary.
{{/option}}
include::options-features.adoc[]
{{#option "`--example` _name_" }}
Run the specified example.
{{/option}}
=== Compilation Options
{{/options}}
include::options-target-triple.adoc[]
{{> section-features }}
include::options-release.adoc[]
### Compilation Options
=== Output Options
{{#options}}
include::options-target-dir.adoc[]
{{> options-target-triple }}
=== Display Options
{{> options-release }}
include::options-display.adoc[]
{{/options}}
include::options-message-format.adoc[]
### Output Options
=== Manifest Options
{{#options}}
{{> options-target-dir }}
{{/options}}
include::options-manifest-path.adoc[]
### Display Options
include::options-locked.adoc[]
{{#options}}
=== Common Options
{{> options-display }}
include::options-common.adoc[]
{{> options-message-format }}
=== Miscellaneous Options
{{/options}}
include::options-jobs.adoc[]
### Manifest Options
include::section-profiles.adoc[]
{{#options}}
include::section-environment.adoc[]
{{> options-manifest-path }}
include::section-exit-status.adoc[]
{{> options-locked }}
== EXAMPLES
{{/options}}
. Build the local package and run its main target (assuming only one binary):
{{> section-options-common }}
cargo run
### Miscellaneous Options
. Run an example with extra arguments:
{{#options}}
{{> options-jobs }}
{{/options}}
cargo run --example exname -- --exoption exarg1 exarg2
{{> section-profiles }}
== SEE ALSO
man:cargo[1], man:cargo-build[1]
{{> section-environment }}
{{> section-exit-status }}
## EXAMPLES
1. Build the local package and run its main target (assuming only one binary):
cargo run
2. Run an example with extra arguments:
cargo run --example exname -- --exoption exarg1 exarg2
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-build" 1}}

104
src/doc/man/cargo-rustc.md
View File

@ -1,94 +1,104 @@
= cargo-rustc(1)
:idprefix: cargo_rustc_
:doctype: manpage
:actionverb: Build
# cargo-rustc(1)
{{*set actionverb="Build"}}
== NAME
## NAME
cargo-rustc - Compile the current package, and pass extra options to the compiler
== SYNOPSIS
## SYNOPSIS
`cargo rustc [_OPTIONS_] [-- _ARGS_]`
`cargo rustc` [_options_] [`--` _args_]
== DESCRIPTION
## DESCRIPTION
The specified target for the current package (or package specified by `-p` if
provided) will be compiled along with all of its dependencies. The specified
_ARGS_ will all be passed to the final compiler invocation, not any of the
_args_ will all be passed to the final compiler invocation, not any of the
dependencies. Note that the compiler will still unconditionally receive
arguments such as `-L`, `--extern`, and `--crate-type`, and the specified
_ARGS_ will simply be added to the compiler invocation.
_args_ will simply be added to the compiler invocation.
See https://doc.rust-lang.org/rustc/index.html for documentation on rustc
See <https://doc.rust-lang.org/rustc/index.html> for documentation on rustc
flags.
include::description-one-target.adoc[]
{{> description-one-target }}
To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS`
linkcargo:reference/environment-variables.html[environment variable] or the
`build.rustflags` linkcargo:reference/config.html[config value].
[environment variable](../reference/environment-variables.html) or the
`build.rustflags` [config value](../reference/config.html).
== OPTIONS
## OPTIONS
=== Package Selection
{{> section-options-package }}
include::options-package.adoc[]
=== Target Selection
### Target Selection
When no target selection options are given, `cargo rustc` will build all
binary and library targets of the selected package.
include::options-targets.adoc[]
{{> options-targets }}
include::options-features.adoc[]
{{> section-features }}
=== Compilation Options
### Compilation Options
include::options-target-triple.adoc[]
{{#options}}
include::options-release.adoc[]
{{> options-target-triple }}
=== Output Options
{{> options-release }}
include::options-target-dir.adoc[]
{{/options}}
=== Display Options
### Output Options
include::options-display.adoc[]
{{#options}}
{{> options-target-dir }}
{{/options}}
include::options-message-format.adoc[]
### Display Options
=== Manifest Options
{{#options}}
include::options-manifest-path.adoc[]
{{> options-display }}
include::options-locked.adoc[]
{{> options-message-format }}
=== Common Options
{{/options}}
include::options-common.adoc[]
### Manifest Options
=== Miscellaneous Options
{{#options}}
include::options-jobs.adoc[]
{{> options-manifest-path }}
include::section-profiles.adoc[]
{{> options-locked }}
include::section-environment.adoc[]
{{/options}}
include::section-exit-status.adoc[]
{{> section-options-common }}
== EXAMPLES
### Miscellaneous Options
. Check if your package (not including dependencies) uses unsafe code:
{{#options}}
{{> options-jobs }}
{{/options}}
cargo rustc --lib -- -D unsafe-code
{{> section-profiles }}
. Try an experimental flag on the nightly compiler, such as this which prints
the size of every type:
{{> section-environment }}
cargo rustc --lib -- -Z print-type-sizes
{{> section-exit-status }}
== SEE ALSO
man:cargo[1], man:cargo-build[1], man:rustc[1]
## EXAMPLES
1. Check if your package (not including dependencies) uses unsafe code:
cargo rustc --lib -- -D unsafe-code
2. Try an experimental flag on the nightly compiler, such as this which prints
the size of every type:
cargo rustc --lib -- -Z print-type-sizes
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-build" 1}}, {{man "rustc" 1}}

106
src/doc/man/cargo-rustdoc.md
View File

@ -1,98 +1,108 @@
= cargo-rustdoc(1)
:idprefix: cargo_rustdoc_
:doctype: manpage
:actionverb: Document
# cargo-rustdoc(1)
{{*set actionverb="Document"}}
== NAME
## NAME
cargo-rustdoc - Build a package's documentation, using specified custom flags
== SYNOPSIS
## SYNOPSIS
`cargo rustdoc [_OPTIONS_] [-- _ARGS_]`
`cargo rustdoc` [_options_] [`--` _args_]
== DESCRIPTION
## DESCRIPTION
The specified target for the current package (or package specified by `-p` if
provided) will be documented with the specified _ARGS_ being passed to the
provided) will be documented with the specified _args_ being passed to the
final rustdoc invocation. Dependencies will not be documented as part of this
command. Note that rustdoc will still unconditionally receive arguments such
as `-L`, `--extern`, and `--crate-type`, and the specified _ARGS_ will simply
as `-L`, `--extern`, and `--crate-type`, and the specified _args_ will simply
be added to the rustdoc invocation.
See https://doc.rust-lang.org/rustdoc/index.html for documentation on rustdoc
See <https://doc.rust-lang.org/rustdoc/index.html> for documentation on rustdoc
flags.
include::description-one-target.adoc[]
{{> description-one-target }}
To pass flags to all rustdoc processes spawned by Cargo, use the
`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable]
or the `build.rustdocflags` linkcargo:reference/config.html[config value].
`RUSTDOCFLAGS` [environment variable](../reference/environment-variables.html)
or the `build.rustdocflags` [config value](../reference/config.html).
== OPTIONS
## OPTIONS
=== Documentation Options
### Documentation Options
*--open*::
Open the docs in a browser after building them. This will use your default
browser unless you define another one in the `BROWSER` environment
variable.
{{#options}}
=== Package Selection
{{#option "`--open`" }}
Open the docs in a browser after building them. This will use your default
browser unless you define another one in the `BROWSER` environment variable.
{{/option}}
include::options-package.adoc[]
{{/options}}
=== Target Selection
{{> section-options-package }}
### Target Selection
When no target selection options are given, `cargo rustdoc` will document all
binary and library targets of the selected package. The binary will be skipped
if its name is the same as the lib target. Binaries are skipped if they have
`required-features` that are missing.
include::options-targets.adoc[]
{{> options-targets }}
include::options-features.adoc[]
{{> section-features }}
=== Compilation Options
### Compilation Options
include::options-target-triple.adoc[]
{{#options}}
include::options-release.adoc[]
{{> options-target-triple }}
=== Output Options
{{> options-release }}
include::options-target-dir.adoc[]
{{/options}}
=== Display Options
### Output Options
include::options-display.adoc[]
{{#options}}
{{> options-target-dir }}
{{/options}}
include::options-message-format.adoc[]
### Display Options
=== Manifest Options
{{#options}}
{{> options-display }}
include::options-manifest-path.adoc[]
{{> options-message-format }}
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
{{/options}}
=== Miscellaneous Options
{{> section-options-common }}
include::options-jobs.adoc[]
### Miscellaneous Options
include::section-profiles.adoc[]
{{#options}}
{{> options-jobs }}
{{/options}}
include::section-environment.adoc[]
{{> section-profiles }}
include::section-exit-status.adoc[]
{{> section-environment }}
== EXAMPLES
{{> section-exit-status }}
. Build documentation with custom CSS included from a given file:
## EXAMPLES
cargo rustdoc --lib -- --extend-css extra.css
1. Build documentation with custom CSS included from a given file:
== SEE ALSO
man:cargo[1], man:cargo-doc[1], man:rustdoc[1]
cargo rustdoc --lib -- --extend-css extra.css
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-doc" 1}}, {{man "rustdoc" 1}}

53
src/doc/man/cargo-search.md
View File

@ -1,49 +1,52 @@
= cargo-search(1)
:idprefix: cargo_search_
:doctype: manpage
# cargo-search(1)
== NAME
## NAME
cargo-search - Search packages in crates.io
== SYNOPSIS
## SYNOPSIS
`cargo search [_OPTIONS_] [_QUERY_...]`
`cargo search` [_options_] [_query_...]
== DESCRIPTION
## DESCRIPTION
This performs a textual search for crates on https://crates.io. The matching
This performs a textual search for crates on <https://crates.io>. The matching
crates will be displayed along with their description in TOML format suitable
for copying into a `Cargo.toml` manifest.
== OPTIONS
## OPTIONS
=== Search Options
### Search Options
*--limit* _LIMIT_::
Limit the number of results (default: 10, max: 100).
{{#options}}
include::options-index.adoc[]
{{#option "`--limit` _limit_" }}
Limit the number of results (default: 10, max: 100).
{{/option}}
include::options-registry.adoc[]
{{> options-index }}
=== Display Options
{{> options-registry }}
include::options-display.adoc[]
{{/options}}
=== Common Options
### Display Options
include::options-common.adoc[]
{{#options}}
{{> options-display }}
{{/options}}
include::section-environment.adoc[]
{{> section-options-common }}
include::section-exit-status.adoc[]
{{> section-environment }}
== EXAMPLES
{{> section-exit-status }}
. Search for a package from crates.io:
## EXAMPLES
cargo search serde
1. Search for a package from crates.io:
== SEE ALSO
man:cargo[1], man:cargo-install[1], man:cargo-publish[1]
cargo search serde
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-install" 1}}, {{man "cargo-publish" 1}}

125
src/doc/man/cargo-test.md
View File

@ -1,18 +1,16 @@
= cargo-test(1)
:idprefix: cargo_test_
:doctype: manpage
:actionverb: Test
:nouns: tests
# cargo-test(1)
{{*set actionverb="Test"}}
{{*set nouns="tests"}}
== NAME
## NAME
cargo-test - Execute unit and integration tests of a package
== SYNOPSIS
## SYNOPSIS
`cargo test [_OPTIONS_] [TESTNAME] [-- _TEST-OPTIONS_]`
`cargo test` [_options_] [_testname_] [`--` _test-options_]
== DESCRIPTION
## DESCRIPTION
Compile and execute unit and integration tests.
@ -21,7 +19,7 @@ dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's
built in unit-test and micro-benchmarking framework). If you're passing
arguments to both Cargo and the binary, the ones after `--` go to the binary,
the ones before go to Cargo. For details about libtest's arguments see the
output of `cargo test \-- --help`.
output of `cargo test -- --help`.
As an example, this will filter for tests with `foo` in their name and run them
on 3 threads in parallel:
@ -30,7 +28,7 @@ on 3 threads in parallel:
Tests are built with the `--test` option to `rustc` which creates an
executable with a `main` function that automatically runs all functions
annotated with the `\#[test]` attribute in multiple threads. `#[bench]`
annotated with the `#[test]` attribute in multiple threads. `#[bench]`
annotated functions will also be run with one iteration to verify that they
are functional.
@ -40,20 +38,18 @@ function to handle running tests.
Documentation tests are also run by default, which is handled by `rustdoc`. It
extracts code samples from documentation comments and executes them. See the
link:https://doc.rust-lang.org/rustdoc/[rustdoc book] for more information on
[rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information on
writing doc tests.
== OPTIONS
## OPTIONS
=== Test Options
### Test Options
include::options-test.adoc[]
{{> options-test }}
=== Package Selection
{{> section-package-selection }}
include::options-packages.adoc[]
=== Target Selection
### Target Selection
When no target selection options are given, `cargo test` will build the
following targets of the selected packages:
@ -78,31 +74,42 @@ library in the manifest.
Binary targets are automatically built if there is an integration test or
benchmark. This allows an integration test to execute the binary to exercise
and test its behavior. The `CARGO_BIN_EXE_<name>`
linkcargo:reference/environment-variables.html#environment-variables-cargo-sets-for-crates[environment variable]
and test its behavior. The `CARGO_bin_EXE_<name>`
[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates)
is set when the integration test is built so that it can use the
link:https://doc.rust-lang.org/std/macro.env.html[`env` macro] to locate the
[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the
executable.
include::options-targets.adoc[]
{{> options-targets }}
*--doc*::
Test only the library's documentation. This cannot be mixed with other
target options.
{{#options}}
include::options-features.adoc[]
{{#option "`--doc`" }}
Test only the library's documentation. This cannot be mixed with other
target options.
{{/option}}
=== Compilation Options
{{/options}}
include::options-target-triple.adoc[]
{{> section-features }}
include::options-release.adoc[]
### Compilation Options
=== Output Options
{{#options}}
include::options-target-dir.adoc[]
{{> options-target-triple }}
=== Display Options
{{> options-release }}
{{/options}}
### Output Options
{{#options}}
{{> options-target-dir }}
{{/options}}
### Display Options
By default the Rust test harness hides output from test execution to keep
results readable. Test output can be recovered (e.g., for debugging) by passing
@ -110,21 +117,27 @@ results readable. Test output can be recovered (e.g., for debugging) by passing
cargo test -- --nocapture
include::options-display.adoc[]
{{#options}}
include::options-message-format.adoc[]
{{> options-display }}
=== Manifest Options
{{> options-message-format }}
include::options-manifest-path.adoc[]
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
include::options-common.adoc[]
{{> options-manifest-path }}
=== Miscellaneous Options
{{> options-locked }}
{{/options}}
{{> section-options-common }}
### Miscellaneous Options
The `--jobs` argument affects the building of the test executable but does not
affect how many threads are used when running the tests. The Rust test harness
@ -132,9 +145,13 @@ includes an option to control the number of threads used:
cargo test -j 2 -- --test-threads=2
include::options-jobs.adoc[]
{{#options}}
include::section-profiles.adoc[]
{{> options-jobs }}
{{/options}}
{{> section-profiles }}
Unit tests are separate executable artifacts which use the `test`/`bench`
profiles. Example targets are built the same as with `cargo build` (using the
@ -144,23 +161,23 @@ which case they use the `test`/`bench` profiles. Library targets are built
with the `dev`/`release` profiles when linked to an integration test, binary,
or doctest.
include::section-environment.adoc[]
{{> section-environment }}
include::section-exit-status.adoc[]
{{> section-exit-status }}
== EXAMPLES
## EXAMPLES
. Execute all the unit and integration tests of the current package:
1. Execute all the unit and integration tests of the current package:
cargo test
cargo test
. Run only tests whose names match against a filter string:
2. Run only tests whose names match against a filter string:
cargo test name_filter
cargo test name_filter
. Run only a specific test within a specific integration test:
3. Run only a specific test within a specific integration test:
cargo test --test int_test_name -- modname::test_name
cargo test --test int_test_name -- modname::test_name
== SEE ALSO
man:cargo[1], man:cargo-bench[1]
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-bench" 1}}

278
src/doc/man/cargo-tree.md
View File

@ -1,23 +1,21 @@
= cargo-tree(1)
:idprefix: cargo_tree_
:doctype: manpage
:actionverb: Display
:noall: true
# cargo-tree(1)
{{*set actionverb="Display"}}
{{*set noall=true}}
== NAME
## NAME
cargo-tree - Display a tree visualization of a dependency graph
== SYNOPSIS
## SYNOPSIS
`cargo tree [_OPTIONS_]`
`cargo tree` [_options_]
== DESCRIPTION
## DESCRIPTION
This command will display a tree of dependencies to the terminal. An example
of a simple project that depends on the "rand" package:
----
```
myproject v0.1.0 (/myproject)
└── rand v0.7.3
├── getrandom v0.1.14
@ -31,7 +29,7 @@ myproject v0.1.0 (/myproject)
└── rand_core v0.5.1 (*)
[build-dependencies]
└── cc v1.0.50
----
```
Packages marked with `(*)` have been "de-duplicated". The dependencies for the
package have already been shown elswhere in the graph, and so are not
@ -41,187 +39,201 @@ The `-e` flag can be used to select the dependency kinds to display. The
"features" kind changes the output to display the features enabled by
each dependency. For example, `cargo tree -e features`:
----
```
myproject v0.1.0 (/myproject)
└── log feature "serde"
└── log v0.4.8
├── serde v1.0.106
└── cfg-if feature "default"
└── cfg-if v0.1.10
----
```
In this tree, `myproject` depends on `log` with the `serde` feature. `log` in
turn depends on `cfg-if` with "default" features. When using `-e features` it
can be helpful to use `-i` flag to show how the features flow into a package.
See the examples below for more detail.
== OPTIONS
## OPTIONS
=== Tree Options
### Tree Options
{{#options}}
{{#option "`-i` _spec_" "`--invert` _spec_" }}
Show the reverse dependencies for the given package. This flag will invert
the tree and display the packages that depend on the given package.
*-i* _SPEC_::
*--invert* _SPEC_::
Show the reverse dependencies for the given package. This flag will invert
the tree and display the packages that depend on the given package.
+
Note that in a workspace, by default it will only display the package's
reverse dependencies inside the tree of the workspace member in the current
directory. The `--workspace` flag can be used to extend it so that it will
show the package's reverse dependencies across the entire workspace. The `-p`
flag can be used to display the package's reverse dependencies only with the
subtree of the package given to `-p`.
{{/option}}
*--no-dedupe*::
Do not de-duplicate repeated dependencies. Usually, when a package has
already displayed its dependencies, further occurrences will not
re-display its dependencies, and will include a `(*)` to indicate it has
already been shown. This flag will cause those duplicates to be repeated.
{{#option "`--no-dedupe`" }}
Do not de-duplicate repeated dependencies. Usually, when a package has already
displayed its dependencies, further occurrences will not re-display its
dependencies, and will include a `(*)` to indicate it has already been shown.
This flag will cause those duplicates to be repeated.
{{/option}}
{{#option "`-d`" "`--duplicates`" }}
Show only dependencies which come in multiple versions (implies `--invert`).
When used with the `-p` flag, only shows duplicates within the subtree of the
given package.
*-d*::
*--duplicates*::
Show only dependencies which come in multiple versions (implies
`--invert`). When used with the `-p` flag, only shows duplicates within
the subtree of the given package.
+
It can be beneficial for build times and executable sizes to avoid building
that same package multiple times. This flag can help identify the offending
packages. You can then investigate if the package that depends on the
duplicate with the older version can be updated to the newer version so that
only one instance is built.
{{/option}}
{{#option "`-e` _kinds_" "`--edges` _kinds_" }}
The dependency kinds to display. Takes a comma separated list of values:
- `all` — Show all edge kinds.
- `normal` — Show normal dependencies.
- `build` — Show build dependencies.
- `dev` — Show development dependencies.
- `features` — Show features enabled by each dependency. If this is the only
kind given, then it will automatically include the other dependency kinds.
- `no-normal` — Do not include normal dependencies.
- `no-build` — Do not include build dependencies.
- `no-dev` — Do not include development dependencies.
*-e* _KINDS_::
*--edges* _KINDS_::
The dependency kinds to display. Takes a comma separated list of values:
+
- `all` — Show all edge kinds.
- `normal` — Show normal dependencies.
- `build` — Show build dependencies.
- `dev` — Show development dependencies.
- `features` — Show features enabled by each dependency. If this is
the only kind given, then it will automatically include the other
dependency kinds.
- `no-normal` — Do not include normal dependencies.
- `no-build` — Do not include build dependencies.
- `no-dev` — Do not include development dependencies.
+
The `no-` prefixed options cannot be mixed with the other dependency kinds.
+
The default is `normal,build,dev`.
{{/option}}
*--target* _TRIPLE_::
Filter dependencies matching the given target-triple.
The default is the host platform. Use the value `all` to include *all*
targets.
{{#option "`--target` _triple_" }}
Filter dependencies matching the given target-triple. The default is the host
platform. Use the value `all` to include *all* targets.
{{/option}}
=== Tree Formatting Options
{{/options}}
*--charset* _CHARSET_::
Chooses the character set to use for the tree. Valid values are "utf8" or
"ascii". Default is "utf8".
### Tree Formatting Options
{{#options}}
{{#option "`--charset` _charset_" }}
Chooses the character set to use for the tree. Valid values are "utf8" or
"ascii". Default is "utf8".
{{/option}}
{{#option "`-f` _format_" "`--format` _format_" }}
Set the format string for each package. The default is "{p}".
*-f* _FORMAT_::
*--format* _FORMAT_::
Set the format string for each package. The default is "{p}".
+
This is an arbitrary string which will be used to display each package. The following
strings will be replaced with the corresponding value:
+
- `{p}` — The package name.
- `{l}` — The package license.
- `{r}` — The package repository URL.
- `{p}` — The package name.
- `{l}` — The package license.
- `{r}` — The package repository URL.
- `{f}` — Comma-separated list of package features that are enabled.
{{/option}}
*--prefix* _PREFIX_::
Sets how each line is displayed. The _PREFIX_ value can be one of:
+
- `indent` (default) — Shows each line indented as a tree.
- `depth` — Show as a list, with the numeric depth printed before each entry.
- `none` — Show as a flat list.
{{#option "`--prefix` _prefix_" }}
Sets how each line is displayed. The _prefix_ value can be one of:
=== Package Selection
- `indent` (default) — Shows each line indented as a tree.
- `depth` — Show as a list, with the numeric depth printed before each entry.
- `none` — Show as a flat list.
{{/option}}
include::options-packages.adoc[]
{{/options}}
=== Manifest Options
{{> section-package-selection }}
include::options-manifest-path.adoc[]
### Manifest Options
include::options-features.adoc[]
{{#options}}
=== Display Options
{{> options-manifest-path }}
include::options-display.adoc[]
{{> options-locked }}
=== Common Options
{{/options}}
include::options-common.adoc[]
{{> section-features }}
include::options-locked.adoc[]
### Display Options
include::section-environment.adoc[]
{{#options}}
include::section-exit-status.adoc[]
{{> options-display }}
== EXAMPLES
{{/options}}
. Display the tree for the package in the current directory:
{{> section-options-common }}
cargo tree
{{> section-environment }}
. Display all the packages that depend on the `syn` package:
{{> section-exit-status }}
cargo tree -i syn
## EXAMPLES
. Show the features enabled on each package:
1. Display the tree for the package in the current directory:
cargo tree --format "{p} {f}"
cargo tree
. Show all packages that are built multiple times. This can happen if multiple
semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0).
2. Display all the packages that depend on the `syn` package:
cargo tree -d
cargo tree -i syn
. Explain why features are enabled for the `syn` package:
3. Show the features enabled on each package:
cargo tree -e features -i syn
+
The `-e features` flag is used to show features. The `-i` flag is used to
invert the graph so that it displays the packages that depend on `syn`. An
example of what this would display:
+
----
syn v1.0.17
├── syn feature "clone-impls"
│ └── syn feature "default"
│ └── rustversion v1.0.2
│ └── rustversion feature "default"
│ └── myproject v0.1.0 (/myproject)
│ └── myproject feature "default" (command-line)
├── syn feature "default" (*)
├── syn feature "derive"
│ └── syn feature "default" (*)
├── syn feature "full"
│ └── rustversion v1.0.2 (*)
├── syn feature "parsing"
│ └── syn feature "default" (*)
├── syn feature "printing"
│ └── syn feature "default" (*)
├── syn feature "proc-macro"
│ └── syn feature "default" (*)
└── syn feature "quote"
├── syn feature "printing" (*)
└── syn feature "proc-macro" (*)
----
+
To read this graph, you can follow the chain for each feature from the root to
see why it is included. For example, the "full" feature is added by the
`rustversion` crate which is included from `myproject` (with the default
features), and `myproject` is the package selected on the command-line. All
of the other `syn` features are added by the "default" feature ("quote" is
added by "printing" and "proc-macro", both of which are default features).
+
If you're having difficulty cross-referencing the de-duplicated `(*)` entries,
try with the `--no-dedupe` flag to get the full output.
cargo tree --format "{p} {f}"
== SEE ALSO
man:cargo[1], man:cargo-metadata[1]
4. Show all packages that are built multiple times. This can happen if multiple
semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0).
cargo tree -d
5. Explain why features are enabled for the `syn` package:
cargo tree -e features -i syn
The `-e features` flag is used to show features. The `-i` flag is used to
invert the graph so that it displays the packages that depend on `syn`. An
example of what this would display:
```
syn v1.0.17
├── syn feature "clone-impls"
│ └── syn feature "default"
│ └── rustversion v1.0.2
│ └── rustversion feature "default"
│ └── myproject v0.1.0 (/myproject)
│ └── myproject feature "default" (command-line)
├── syn feature "default" (*)
├── syn feature "derive"
│ └── syn feature "default" (*)
├── syn feature "full"
│ └── rustversion v1.0.2 (*)
├── syn feature "parsing"
│ └── syn feature "default" (*)
├── syn feature "printing"
│ └── syn feature "default" (*)
├── syn feature "proc-macro"
│ └── syn feature "default" (*)
└── syn feature "quote"
├── syn feature "printing" (*)
└── syn feature "proc-macro" (*)
```
To read this graph, you can follow the chain for each feature from the root
to see why it is included. For example, the "full" feature is added by the
`rustversion` crate which is included from `myproject` (with the default
features), and `myproject` is the package selected on the command-line. All
of the other `syn` features are added by the "default" feature ("quote" is
added by "printing" and "proc-macro", both of which are default features).
If you're having difficulty cross-referencing the de-duplicated `(*)`
entries, try with the `--no-dedupe` flag to get the full output.
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-metadata" 1}}

66
src/doc/man/cargo-uninstall.md
View File

@ -1,57 +1,63 @@
= cargo-uninstall(1)
:idprefix: cargo_uninstall_
:doctype: manpage
# cargo-uninstall(1)
== NAME
## NAME
cargo-uninstall - Remove a Rust binary
== SYNOPSIS
## SYNOPSIS
`cargo uninstall [_OPTIONS_] [_SPEC_...]`
`cargo uninstall` [_options_] [_spec_...]
== DESCRIPTION
## DESCRIPTION
This command removes a package installed with man:cargo-install[1]. The _SPEC_
This command removes a package installed with {{man "cargo-install" 1}}. The _spec_
argument is a package ID specification of the package to remove (see
man:cargo-pkgid[1]).
{{man "cargo-pkgid" 1}}).
By default all binaries are removed for a crate but the `--bin` and
`--example` flags can be used to only remove particular binaries.
include::description-install-root.adoc[]
{{> description-install-root }}
== OPTIONS
## OPTIONS
=== Install Options
### Install Options
*-p*::
*--package* _SPEC_...::
Package to uninstall.
{{#options}}
*--bin* _NAME_...::
Only uninstall the binary _NAME_.
{{#option "`-p`" "`--package` _spec_..." }}
Package to uninstall.
{{/option}}
*--root* _DIR_::
Directory to uninstall packages from.
{{#option "`--bin` _name_..." }}
Only uninstall the binary _name_.
{{/option}}
=== Display Options
{{#option "`--root` _dir_" }}
Directory to uninstall packages from.
{{/option}}
include::options-display.adoc[]
{{/options}}
=== Common Options
### Display Options
include::options-common.adoc[]
{{#options}}
include::section-environment.adoc[]
{{> options-display }}
include::section-exit-status.adoc[]
{{/options}}
== EXAMPLES
{{> section-options-common }}
. Uninstall a previously installed package.
{{> section-environment }}
cargo uninstall ripgrep
{{> section-exit-status }}
== SEE ALSO
man:cargo[1], man:cargo-install[1]
## EXAMPLES
1. Uninstall a previously installed package.
cargo uninstall ripgrep
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-install" 1}}

95
src/doc/man/cargo-update.md
View File

@ -1,81 +1,90 @@
= cargo-update(1)
:idprefix: cargo_update_
:doctype: manpage
# cargo-update(1)
== NAME
## NAME
cargo-update - Update dependencies as recorded in the local lock file
== SYNOPSIS
## SYNOPSIS
`cargo update [_OPTIONS_]`
`cargo update` [_options_]
== DESCRIPTION
## DESCRIPTION
This command will update dependencies in the `Cargo.lock` file to the latest
version. It requires that the `Cargo.lock` file already exists as generated
by commands such as man:cargo-build[1] or man:cargo-generate-lockfile[1].
by commands such as {{man "cargo-build" 1}} or {{man "cargo-generate-lockfile" 1}}.
== OPTIONS
## OPTIONS
=== Update Options
### Update Options
{{#options}}
{{#option "`-p` _spec_..." "`--package` _spec_..." }}
Update only the specified packages. This flag may be specified
multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format.
*-p* _SPEC_...::
*--package* _SPEC_...::
Update only the specified packages. This flag may be specified
multiple times. See man:cargo-pkgid[1] for the SPEC format.
+
If packages are specified with the `-p` flag, then a conservative update of
the lockfile will be performed. This means that only the dependency specified
by SPEC will be updated. Its transitive dependencies will be updated only if
SPEC cannot be updated without updating dependencies. All other dependencies
will remain locked at their currently recorded versions.
+
If `-p` is not specified, all dependencies are updated.
{{/option}}
*--aggressive*::
When used with `-p`, dependencies of _SPEC_ are forced to update as well.
Cannot be used with `--precise`.
{{#option "`--aggressive`" }}
When used with `-p`, dependencies of _spec_ are forced to update as well.
Cannot be used with `--precise`.
{{/option}}
*--precise* _PRECISE_::
When used with `-p`, allows you to specify a specific version number to
set the package to. If the package comes from a git repository, this can
be a git revision (such as a SHA hash or tag).
{{#option "`--precise` _precise_" }}
When used with `-p`, allows you to specify a specific version number to set
the package to. If the package comes from a git repository, this can be a git
revision (such as a SHA hash or tag).
{{/option}}
*--dry-run*::
Displays what would be updated, but doesn't actually write the lockfile.
{{#option "`--dry-run`" }}
Displays what would be updated, but doesn't actually write the lockfile.
{{/option}}
=== Display Options
{{/options}}
include::options-display.adoc[]
### Display Options
=== Manifest Options
{{#options}}
{{> options-display }}
{{/options}}
include::options-manifest-path.adoc[]
### Manifest Options
include::options-locked.adoc[]
{{#options}}
=== Common Options
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
include::section-environment.adoc[]
{{/options}}
include::section-exit-status.adoc[]
{{> section-options-common }}
== EXAMPLES
{{> section-environment }}
. Update all dependencies in the lockfile:
{{> section-exit-status }}
cargo update
## EXAMPLES
. Update only specific dependencies:
1. Update all dependencies in the lockfile:
cargo update -p foo -p bar
cargo update
. Set a specific dependency to a specific version:
2. Update only specific dependencies:
cargo update -p foo --precise 1.2.3
cargo update -p foo -p bar
== SEE ALSO
man:cargo[1], man:cargo-generate-lockfile[1]
3. Set a specific dependency to a specific version:
cargo update -p foo --precise 1.2.3
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}

97
src/doc/man/cargo-vendor.md
View File

@ -1,16 +1,14 @@
= cargo-vendor(1)
:idprefix: cargo_vendor_
:doctype: manpage
# cargo-vendor(1)
== NAME
## NAME
cargo-vendor - Vendor all dependencies locally
== SYNOPSIS
## SYNOPSIS
`cargo vendor [_OPTIONS_] [_PATH_]`
`cargo vendor` [_options_] [_path_]
== DESCRIPTION
## DESCRIPTION
This cargo subcommand will vendor all crates.io and git dependencies for a
project into the specified directory at `<path>`. After this command completes
@ -21,62 +19,75 @@ specified with the `-s` option.
The `cargo vendor` command will also print out the configuration necessary
to use the vendored sources, which you will need to add to `.cargo/config.toml`.
== OPTIONS
## OPTIONS
=== Vendor Options
### Vendor Options
*-s* _MANIFEST_::
*--sync* _MANIFEST_::
Specify extra `Cargo.toml` manifests to workspaces which should also be
vendored and synced to the output.
{{#options}}
*--no-delete*::
Don't delete the "vendor" directory when vendoring, but rather keep all
existing contents of the vendor directory
{{#option "`-s` _manifest_" "`--sync` _manifest_" }}
Specify extra `Cargo.toml` manifests to workspaces which should also be
vendored and synced to the output.
{{/option}}
*--respect-source-config*::
Instead of ignoring `[source]` configuration by default in `.cargo/config.toml`
read it and use it when downloading crates from crates.io, for example
{{#option "`--no-delete`" }}
Don't delete the "vendor" directory when vendoring, but rather keep all
existing contents of the vendor directory
{{/option}}
*--versioned-dirs*::
Normally versions are only added to disambiguate multiple versions of the
same package. This option causes all directories in the "vendor" directory
to be versioned, which makes it easier to track the history of vendored
packages over time, and can help with the performance of re-vendoring when
only a subset of the packages have changed.
{{#option "`--respect-source-config`" }}
Instead of ignoring `[source]` configuration by default in `.cargo/config.toml`
read it and use it when downloading crates from crates.io, for example
{{/option}}
=== Manifest Options
{{#option "`--versioned-dirs`" }}
Normally versions are only added to disambiguate multiple versions of the
same package. This option causes all directories in the "vendor" directory
to be versioned, which makes it easier to track the history of vendored
packages over time, and can help with the performance of re-vendoring when
only a subset of the packages have changed.
{{/option}}
include::options-manifest-path.adoc[]
{{/options}}
=== Display Options
### Manifest Options
include::options-display.adoc[]
{{#options}}
=== Common Options
{{> options-manifest-path }}
include::options-common.adoc[]
{{> options-locked }}
include::options-locked.adoc[]
{{/options}}
include::section-environment.adoc[]
### Display Options
include::section-exit-status.adoc[]
{{#options}}
== EXAMPLES
{{> options-display }}
. Vendor all dependencies into a local "vendor" folder
{{/options}}
cargo vendor
{{> section-options-common }}
. Vendor all dependencies into a local "third-party/vendor" folder
{{> section-environment }}
cargo vendor third-party/vendor
{{> section-exit-status }}
. Vendor the current workspace as well as another to "vendor"
## EXAMPLES
cargo vendor -s ../path/to/Cargo.toml
1. Vendor all dependencies into a local "vendor" folder
== SEE ALSO
man:cargo[1]
cargo vendor
2. Vendor all dependencies into a local "third-party/vendor" folder
cargo vendor third-party/vendor
3. Vendor the current workspace as well as another to "vendor"
cargo vendor -s ../path/to/Cargo.toml
## SEE ALSO
{{man "cargo" 1}}

53
src/doc/man/cargo-verify-project.md
View File

@ -1,16 +1,14 @@
= cargo-verify-project(1)
:idprefix: cargo_verify-project_
:doctype: manpage
# cargo-verify-project(1)
== NAME
## NAME
cargo-verify-project - Check correctness of crate manifest
== SYNOPSIS
## SYNOPSIS
`cargo verify-project [_OPTIONS_]`
`cargo verify-project` [_options_]
== DESCRIPTION
## DESCRIPTION
This command will parse the local manifest and check its validity. It emits a
JSON object with the result. A successful validation will display:
@ -21,37 +19,40 @@ An invalid workspace will display:
{"invalid":"human-readable error message"}
== OPTIONS
## OPTIONS
=== Display Options
### Display Options
include::options-display.adoc[]
{{#options}}
=== Manifest Options
{{> options-display }}
include::options-manifest-path.adoc[]
{{/options}}
include::options-locked.adoc[]
### Manifest Options
=== Common Options
{{#options}}
include::options-common.adoc[]
{{> options-manifest-path }}
include::section-environment.adoc[]
{{> options-locked }}
== Exit Status
{{/options}}
0::
The workspace is OK.
{{> section-options-common }}
1::
The workspace is invalid.
{{> section-environment }}
== EXAMPLES
## EXIT STATUS
. Check the current workspace for errors:
* `0`: The workspace is OK.
* `1`: The workspace is invalid.
cargo verify-project
## EXAMPLES
== SEE ALSO
man:cargo[1], man:cargo-package[1]
1. Check the current workspace for errors:
cargo verify-project
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-package" 1}}

44
src/doc/man/cargo-version.md
View File

@ -1,39 +1,41 @@
= cargo-version(1)
:idprefix: cargo_version_
:doctype: manpage
# cargo-version(1)
== NAME
## NAME
cargo-version - Show version information
== SYNOPSIS
## SYNOPSIS
`cargo version [_OPTIONS_]`
`cargo version` [_options_]
== DESCRIPTION
## DESCRIPTION
Displays the version of Cargo.
== OPTIONS
## OPTIONS
*-v*::
*--verbose*::
Display additional version information.
{{#options}}
== EXAMPLES
{{#option "`-v`" "`--verbose`" }}
Display additional version information.
{{/option}}
. Display the version:
{{/options}}
cargo version
## EXAMPLES
. The version is also available via flags:
1. Display the version:
cargo --version
cargo -V
cargo version
. Display extra version information:
2. The version is also available via flags:
cargo -Vv
cargo --version
cargo -V
== SEE ALSO
man:cargo[1]
3. Display extra version information:
cargo -Vv
## SEE ALSO
{{man "cargo" 1}}

62
src/doc/man/cargo-yank.md
View File

@ -1,16 +1,14 @@
= cargo-yank(1)
:idprefix: cargo_yank_
:doctype: manpage
# cargo-yank(1)
== NAME
## NAME
cargo-yank - Remove a pushed crate from the index
== SYNOPSIS
## SYNOPSIS
`cargo yank [_OPTIONS_] --vers _VERSION_ [_CRATE_]`
`cargo yank` [_options_] `--vers` _version_ [_crate_]
== DESCRIPTION
## DESCRIPTION
The yank command removes a previously published crate's version from the
server's index. This command does not delete any data, and the crate will
@ -21,44 +19,52 @@ download the yanked version to use it. Cargo will, however, not allow any new
crates to be locked to any yanked version.
This command requires you to be authenticated with either the `--token` option
or using man:cargo-login[1].
or using {{man "cargo-login" 1}}.
If the crate name is not specified, it will use the package name from the
current directory.
== OPTIONS
## OPTIONS
=== Yank Options
### Yank Options
*--vers* _VERSION_::
The version to yank or un-yank.
{{#options}}
*--undo*::
Undo a yank, putting a version back into the index.
{{#option "`--vers` _version_" }}
The version to yank or un-yank.
{{/option}}
include::options-token.adoc[]
{{#option "`--undo`" }}
Undo a yank, putting a version back into the index.
{{/option}}
include::options-index.adoc[]
{{> options-token }}
include::options-registry.adoc[]
{{> options-index }}
=== Display Options
{{> options-registry }}
include::options-display.adoc[]
{{/options}}
=== Common Options
### Display Options
include::options-common.adoc[]
{{#options}}
include::section-environment.adoc[]
{{> options-display }}
include::section-exit-status.adoc[]
{{/options}}
== EXAMPLES
{{> section-options-common }}
. Yank a crate from the index:
{{> section-environment }}
cargo yank --vers 1.0.7 foo
{{> section-exit-status }}
== SEE ALSO
man:cargo[1], man:cargo-login[1], man:cargo-publish[1]
## EXAMPLES
1. Yank a crate from the index:
cargo yank --vers 1.0.7 foo
## SEE ALSO
{{man "cargo" 1}}, {{man "cargo-login" 1}}, {{man "cargo-publish" 1}}

287
src/doc/man/cargo.md
View File

@ -1,226 +1,233 @@
= cargo(1)
:doctype: manpage
# cargo(1)
== NAME
## NAME
cargo - The Rust package manager
== SYNOPSIS
## SYNOPSIS
[%hardbreaks]
`cargo [_OPTIONS_] _COMMAND_ [_ARGS_]`
`cargo [_OPTIONS_] --version`
`cargo [_OPTIONS_] --list`
`cargo [_OPTIONS_] --help`
`cargo [_OPTIONS_] --explain _CODE_`
`cargo` [_options_] _command_ [_args_]\
`cargo` [_options_] `--version`\
`cargo` [_options_] `--list`\
`cargo` [_options_] `--help`\
`cargo` [_options_] `--explain` _code_
== DESCRIPTION
## DESCRIPTION
This program is a package manager and build tool for the Rust language,
available at <https://rust-lang.org>.
== COMMANDS
## COMMANDS
=== Build Commands
### Build Commands
man:cargo-bench[1]::
Execute benchmarks of a package.
{{man "cargo-bench" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Execute benchmarks of a package.
man:cargo-build[1]::
Compile a package.
{{man "cargo-build" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Compile a package.
man:cargo-check[1]::
Check a local package and all of its dependencies for errors.
{{man "cargo-check" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Check a local package and all of its dependencies for errors.
man:cargo-clean[1]::
Remove artifacts that Cargo has generated in the past.
{{man "cargo-clean" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Remove artifacts that Cargo has generated in the past.
man:cargo-doc[1]::
Build a package's documentation.
{{man "cargo-doc" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Build a package's documentation.
man:cargo-fetch[1]::
Fetch dependencies of a package from the network.
{{man "cargo-fetch" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Fetch dependencies of a package from the network.
man:cargo-fix[1]::
Automatically fix lint warnings reported by rustc.
{{man "cargo-fix" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Automatically fix lint warnings reported by rustc.
man:cargo-run[1]::
Run a binary or example of the local package.
{{man "cargo-run" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Run a binary or example of the local package.
man:cargo-rustc[1]::
Compile a package, and pass extra options to the compiler.
{{man "cargo-rustc" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Compile a package, and pass extra options to the compiler.
man:cargo-rustdoc[1]::
Build a package's documentation, using specified custom flags.
{{man "cargo-rustdoc" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Build a package's documentation, using specified custom flags.
man:cargo-test[1]::
Execute unit and integration tests of a package.
{{man "cargo-test" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Execute unit and integration tests of a package.
=== Manifest Commands
### Manifest Commands
man:cargo-generate-lockfile[1]::
Generate `Cargo.lock` for a project.
{{man "cargo-generate-lockfile" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Generate `Cargo.lock` for a project.
man:cargo-locate-project[1]::
Print a JSON representation of a `Cargo.toml` file's location.
{{man "cargo-locate-project" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Print a JSON representation of a `Cargo.toml` file's location.
man:cargo-metadata[1]::
Output the resolved dependencies of a package, the concrete used versions
including overrides, in machine-readable format.
{{man "cargo-metadata" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Output the resolved dependencies of a package in machine-readable format.
man:cargo-pkgid[1]::
Print a fully qualified package specification.
{{man "cargo-pkgid" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Print a fully qualified package specification.
man:cargo-tree[1]::
Display a tree visualization of a dependency graph.
{{man "cargo-tree" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Display a tree visualization of a dependency graph.
man:cargo-update[1]::
Update dependencies as recorded in the local lock file.
{{man "cargo-update" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Update dependencies as recorded in the local lock file.
man:cargo-vendor[1]::
Vendor all dependencies locally.
{{man "cargo-vendor" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Vendor all dependencies locally.
man:cargo-verify-project[1]::
Check correctness of crate manifest.
{{man "cargo-verify-project" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Check correctness of crate manifest.
=== Package Commands
### Package Commands
man:cargo-init[1]::
Create a new Cargo package in an existing directory.
{{man "cargo-init" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Create a new Cargo package in an existing directory.
man:cargo-install[1]::
Build and install a Rust binary.
{{man "cargo-install" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Build and install a Rust binary.
man:cargo-new[1]::
Create a new Cargo package.
{{man "cargo-new" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Create a new Cargo package.
man:cargo-search[1]::
Search packages in crates.io.
{{man "cargo-search" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Search packages in crates.io.
man:cargo-uninstall[1]::
Remove a Rust binary.
{{man "cargo-uninstall" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Remove a Rust binary.
=== Publishing Commands
### Publishing Commands
man:cargo-login[1]::
Save an API token from the registry locally.
{{man "cargo-login" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Save an API token from the registry locally.
man:cargo-owner[1]::
Manage the owners of a crate on the registry.
{{man "cargo-owner" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Manage the owners of a crate on the registry.
man:cargo-package[1]::
Assemble the local package into a distributable tarball.
{{man "cargo-package" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Assemble the local package into a distributable tarball.
man:cargo-publish[1]::
Upload a package to the registry.
{{man "cargo-publish" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Upload a package to the registry.
man:cargo-yank[1]::
Remove a pushed crate from the index.
{{man "cargo-yank" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Remove a pushed crate from the index.
=== General Commands
### General Commands
man:cargo-help[1]::
Display help information about Cargo.
{{man "cargo-help" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Display help information about Cargo.
man:cargo-version[1]::
Show version information.
{{man "cargo-version" 1}}\
&nbsp;&nbsp;&nbsp;&nbsp;Show version information.
== OPTIONS
## OPTIONS
=== Special Options
### Special Options
*-V*::
*--version*::
Print version info and exit. If used with `--verbose`, prints extra
information.
{{#options}}
*--list*::
List all installed Cargo subcommands. If used with `--verbose`, prints
extra information.
{{#option "`-V`" "`--version`" }}
Print version info and exit. If used with `--verbose`, prints extra
information.
{{/option}}
*--explain _CODE_*::
Run `rustc --explain CODE` which will print out a detailed explanation of
an error message (for example, `E0004`).
{{#option "`--list`" }}
List all installed Cargo subcommands. If used with `--verbose`, prints extra
information.
{{/option}}
=== Display Options
{{#option "`--explain` _code_" }}
Run `rustc --explain CODE` which will print out a detailed explanation of an
error message (for example, `E0004`).
{{/option}}
include::options-display.adoc[]
{{/options}}
=== Manifest Options
### Display Options
include::options-locked.adoc[]
{{#options}}
=== Common Options
{{> options-display }}
include::options-common.adoc[]
{{/options}}
include::section-environment.adoc[]
### Manifest Options
include::section-exit-status.adoc[]
{{#options}}
{{> options-locked }}
{{/options}}
== FILES
{{> section-options-common }}
`~/.cargo/`::
Default location for Cargo's "home" directory where it stores various
files. The location can be changed with the `CARGO_HOME` environment
variable.
{{> section-environment }}
`$CARGO_HOME/bin/`::
Binaries installed by man:cargo-install[1] will be located here. If using
rustup, executables distributed with Rust are also located here.
{{> section-exit-status }}
`$CARGO_HOME/config.toml`::
The global configuration file. See linkcargo:reference/config.html[the reference]
for more information about configuration files.
## FILES
`.cargo/config.toml`::
Cargo automatically searches for a file named `.cargo/config.toml` in the
current directory, and all parent directories. These configuration files
will be merged with the global configuration file.
`~/.cargo/`\
&nbsp;&nbsp;&nbsp;&nbsp;Default location for Cargo's "home" directory where it
stores various files. The location can be changed with the `CARGO_HOME`
environment variable.
`$CARGO_HOME/credentials.toml`::
Private authentication information for logging in to a registry.
`$CARGO_HOME/bin/`\
&nbsp;&nbsp;&nbsp;&nbsp;Binaries installed by {{man "cargo-install" 1}} will be located here. If using
rustup, executables distributed with Rust are also located here.
`$CARGO_HOME/registry/`::
This directory contains cached downloads of the registry index and any
downloaded dependencies.
`$CARGO_HOME/config.toml`\
&nbsp;&nbsp;&nbsp;&nbsp;The global configuration file. See [the reference](../reference/config.html)
for more information about configuration files.
`$CARGO_HOME/git/`::
This directory contains cached downloads of git dependencies.
`.cargo/config.toml`\
&nbsp;&nbsp;&nbsp;&nbsp;Cargo automatically searches for a file named `.cargo/config.toml` in the
current directory, and all parent directories. These configuration files
will be merged with the global configuration file.
`$CARGO_HOME/credentials.toml`\
&nbsp;&nbsp;&nbsp;&nbsp;Private authentication information for logging in to a registry.
`$CARGO_HOME/registry/`\
&nbsp;&nbsp;&nbsp;&nbsp;This directory contains cached downloads of the registry index and any
downloaded dependencies.
`$CARGO_HOME/git/`\
&nbsp;&nbsp;&nbsp;&nbsp;This directory contains cached downloads of git dependencies.
Please note that the internal structure of the `$CARGO_HOME` directory is not
stable yet and may be subject to change.
== EXAMPLES
## EXAMPLES
. Build a local package and all of its dependencies:
1. Build a local package and all of its dependencies:
cargo build
cargo build
. Build a package with optimizations:
2. Build a package with optimizations:
cargo build --release
cargo build --release
. Run tests for a cross-compiled target:
3. Run tests for a cross-compiled target:
cargo test --target i686-unknown-linux-gnu
cargo test --target i686-unknown-linux-gnu
. Create a new package that builds an executable:
4. Create a new package that builds an executable:
cargo new foobar
cargo new foobar
. Create a package in the current directory:
5. Create a package in the current directory:
mkdir foo && cd foo
cargo init .
mkdir foo && cd foo
cargo init .
. Learn about a command's options and usage:
6. Learn about a command's options and usage:
cargo help clean
cargo help clean
== BUGS
## BUGS
See https://github.com/rust-lang/cargo/issues for issues.
See <https://github.com/rust-lang/cargo/issues> for issues.
== SEE ALSO
man:rustc[1], man:rustdoc[1]
## SEE ALSO
{{man "rustc" 1}}, {{man "rustdoc" 1}}

2
src/doc/man/includes/description-install-root.md
View File

@ -2,6 +2,6 @@ The installation root is determined, in order of precedence:
- `--root` option
- `CARGO_INSTALL_ROOT` environment variable
- `install.root` Cargo linkcargo:reference/config.html[config value]
- `install.root` Cargo [config value](../reference/config.html)
- `CARGO_HOME` environment variable
- `$HOME/.cargo`

2
src/doc/man/includes/description-new-authors.md
View File

@ -20,5 +20,5 @@ The email address is optional and is determined from:
- `user.email` git configuration value
- `EMAIL` environment variable
See linkcargo:reference/config.html[the reference] for more information about
See [the reference](../reference/config.html) for more information about
configuration files.

28
src/doc/man/includes/options-display.md
View File

@ -1,22 +1,22 @@
*-v*::
*--verbose*::
Use verbose output. May be specified twice for "very verbose" output which
includes extra output such as dependency warnings and build script output.
May also be specified with the `term.verbose`
linkcargo:reference/config.html[config value].
{{#option "`-v`" "`--verbose`"}}
Use verbose output. May be specified twice for "very verbose" output which
includes extra output such as dependency warnings and build script output.
May also be specified with the `term.verbose`
[config value](../reference/config.html).
{{/option}}
*-q*::
*--quiet*::
No output printed to stdout.
{{#option "`-q`" "`--quiet`"}}
No output printed to stdout.
{{/option}}
{{#option "`--color` _when_"}}
Control when colored output is used. Valid values:
*--color* _WHEN_::
Control when colored output is used. Valid values:
+
- `auto` (default): Automatically detect if color support is available on the
terminal.
- `always`: Always display colors.
- `never`: Never display colors.
+
May also be specified with the `term.color`
linkcargo:reference/config.html[config value].
[config value](../reference/config.html).
{{/option}}

5
src/doc/man/includes/options-index.md
View File

@ -1,2 +1,3 @@
*--index* _INDEX_::
The URL of the registry index to use.
{{#option "`--index` _index_"}}
The URL of the registry index to use.
{{/option}}

10
src/doc/man/includes/options-jobs.md
View File

@ -1,5 +1,5 @@
*-j* _N_::
*--jobs* _N_::
Number of parallel jobs to run. May also be specified with the
`build.jobs` linkcargo:reference/config.html[config value]. Defaults to
the number of CPUs.
{{#option "`-j` _N_" "`--jobs` _N_"}}
Number of parallel jobs to run. May also be specified with the
`build.jobs` [config value](../reference/config.html). Defaults to
the number of CPUs.
{{/option}}

33
src/doc/man/includes/options-locked.md
View File

@ -1,24 +1,25 @@
*--frozen*::
*--locked*::
Either of these flags requires that the `Cargo.lock` file is
up-to-date. If the lock file is missing, or it needs to be updated, Cargo will
exit with an error. The `--frozen` flag also prevents Cargo from
attempting to access the network to determine if it is out-of-date.
+
{{#option "`--frozen`" "`--locked`"}}
Either of these flags requires that the `Cargo.lock` file is
up-to-date. If the lock file is missing, or it needs to be updated, Cargo will
exit with an error. The `--frozen` flag also prevents Cargo from
attempting to access the network to determine if it is out-of-date.
These may be used in environments where you want to assert that the
`Cargo.lock` file is up-to-date (such as a CI build) or want to avoid network
access.
{{/option}}
{{#option "`--offline`"}}
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
*--offline*::
Prevents Cargo from accessing the network for any reason. Without this
flag, Cargo will stop with an error if it needs to access the network and
the network is not available. With this flag, Cargo will attempt to
proceed without the network if possible.
+
Beware that this may result in different dependency resolution than online
mode. Cargo will restrict itself to crates that are downloaded locally, even
if there might be a newer version as indicated in the local copy of the index.
See the man:cargo-fetch[1] command to download dependencies before going
See the {{man "cargo-fetch" 1}} command to download dependencies before going
offline.
+
May also be specified with the `net.offline` linkcargo:reference/config.html[config value].
May also be specified with the `net.offline` [config value](../reference/config.html).
{{/option}}

7
src/doc/man/includes/options-manifest-path.md
View File

@ -1,3 +1,4 @@
*--manifest-path* _PATH_::
Path to the `Cargo.toml` file. By default, Cargo searches for the
`Cargo.toml` file in the current directory or any parent directory.
{{#option "`--manifest-path` _path_" }}
Path to the `Cargo.toml` file. By default, Cargo searches for the
`Cargo.toml` file in the current directory or any parent directory.
{{/option}}

11
src/doc/man/includes/options-message-format.md
View File

@ -1,11 +1,11 @@
*--message-format* _FMT_::
The output format for diagnostic messages. Can be specified multiple times
and consists of comma-separated values. Valid values:
+
{{#option "`--message-format` _fmt_" }}
The output format for diagnostic messages. Can be specified multiple times
and consists of comma-separated values. Valid values:
- `human` (default): Display in a human-readable text format.
- `short`: Emit shorter, human-readable text messages.
- `json`: Emit JSON messages to stdout. See
linkcargo:reference/external-tools.html#json-messages[the reference]
[the reference](../reference/external-tools.html#json-messages)
for more details.
- `json-diagnostic-short`: Ensure the `rendered` field of JSON messages contains
the "short" rendering from rustc.
@ -16,3 +16,4 @@
in JSON messages printed, but instead Cargo itself should render the
JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others
coming from rustc are still emitted.
{{/option}}

50
src/doc/man/includes/options-new.md
View File

@ -1,29 +1,39 @@
*--bin*::
Create a package with a binary target (`src/main.rs`).
This is the default behavior.
{{#options}}
*--lib*::
Create a package with a library target (`src/lib.rs`).
{{#option "`--bin`" }}
Create a package with a binary target (`src/main.rs`).
This is the default behavior.
{{/option}}
*--edition* _EDITION_::
Specify the Rust edition to use. Default is 2018.
Possible values: 2015, 2018
{{#option "`--lib`" }}
Create a package with a library target (`src/lib.rs`).
{{/option}}
*--name* _NAME_::
Set the package name. Defaults to the directory name.
{{#option "`--edition` _edition_" }}
Specify the Rust edition to use. Default is 2018.
Possible values: 2015, 2018
{{/option}}
*--vcs* _VCS_::
Initialize a new VCS repository for the given version control system (git,
hg, pijul, or fossil) or do not initialize any version control at all
(none). If not specified, defaults to `git` or the configuration value
`cargo-new.vcs`, or `none` if already inside a VCS repository.
{{#option "`--name` _name_" }}
Set the package name. Defaults to the directory name.
{{/option}}
*--registry* _REGISTRY_::
This sets the `publish` field in `Cargo.toml` to the given registry name
which will restrict publishing only to that registry.
+
Registry names are defined in linkcargo:reference/config.html[Cargo config files].
{{#option "`--vcs` _vcs_" }}
Initialize a new VCS repository for the given version control system (git,
hg, pijul, or fossil) or do not initialize any version control at all
(none). If not specified, defaults to `git` or the configuration value
`cargo-new.vcs`, or `none` if already inside a VCS repository.
{{/option}}
{{#option "`--registry` _registry_" }}
This sets the `publish` field in `Cargo.toml` to the given registry name
which will restrict publishing only to that registry.
Registry names are defined in [Cargo config files](../reference/config.html).
If not specified, the default registry defined by the `registry.default`
config key is used. If the default registry is not set and `--registry` is not
used, the `publish` field will not be set which means that publishing will not
be restricted.
{{/option}}
{{/options}}

13
src/doc/man/includes/options-profile.md
View File

@ -1,6 +1,7 @@
*--profile* _NAME_::
Changes convert:lowercase[{actionverb}] behavior. Currently only `test` is
supported, which will convert:lowercase[{actionverb}] with the
`#[cfg(test)]` attribute enabled. This is useful to have it
convert:lowercase[{actionverb}] unit tests which are usually excluded via
the `cfg` attribute. This does not change the actual profile used.
{{#option "`--profile` _name_" }}
Changes {{lower actionverb}} behavior. Currently only `test` is supported,
which will {{lower actionverb}} with the `#[cfg(test)]` attribute enabled.
This is useful to have it {{lower actionverb}} unit tests which are usually
excluded via the `cfg` attribute. This does not change the actual profile
used.
{{/option}}

10
src/doc/man/includes/options-registry.md
View File

@ -1,4 +1,6 @@
*--registry* _REGISTRY_::
Name of the registry to use. Registry names are defined in linkcargo:reference/config.html[Cargo config files].
If not specified, the default registry is used, which is defined by the
`registry.default` config key which defaults to `crates-io`.
{{#option "`--registry` _registry_"}}
Name of the registry to use. Registry names are defined in [Cargo config
files](../reference/config.html). If not specified, the default registry is used,
which is defined by the `registry.default` config key which defaults to
`crates-io`.
{{/option}}

8
src/doc/man/includes/options-release.md
View File

@ -1,3 +1,5 @@
*--release*::
{actionverb} optimized artifacts with the `release` profile. See the
<<PROFILES>> section for details on how this affects profile selection.
{{#option "`--release`"}}
{{actionverb}} optimized artifacts with the `release` profile. See the
[PROFILES](#profiles) section for details on how this affects profile
selection.
{{/option}}

11
src/doc/man/includes/options-target-dir.md
View File

@ -1,5 +1,6 @@
*--target-dir* _DIRECTORY_::
Directory for all generated artifacts and intermediate files. May also be
specified with the `CARGO_TARGET_DIR` environment variable, or the
`build.target-dir` linkcargo:reference/config.html[config value]. Defaults
to `target` in the root of the workspace.
{{#option "`--target-dir` _directory_"}}
Directory for all generated artifacts and intermediate files. May also be
specified with the `CARGO_TARGET_DIR` environment variable, or the
`build.target-dir` [config value](../reference/config.html). Defaults
to `target` in the root of the workspace.
{{/option}}

19
src/doc/man/includes/options-target-triple.md
View File

@ -1,12 +1,13 @@
*--target* _TRIPLE_::
{actionverb} for the given architecture. The default is the host
architecture. The general format of the triple is
`<arch><sub>-<vendor>-<sys>-<abi>`. Run `rustc --print target-list` for a
list of supported targets.
+
{{#option "`--target` _triple_"}}
{{actionverb}} for the given architecture. The default is the host
architecture. The general format of the triple is
`<arch><sub>-<vendor>-<sys>-<abi>`. Run `rustc --print target-list` for a
list of supported targets.
This may also be specified with the `build.target`
linkcargo:reference/config.html[config value].
+
[config value](../reference/config.html).
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.
[build cache](../guide/build-cache.html) documentation for more details.
{{/option}}

15
src/doc/man/includes/options-targets-lib-bin.md
View File

@ -1,8 +1,11 @@
*--lib*::
{actionverb} the package's library.
{{#option "`--lib`" }}
{{actionverb}} the package's library.
{{/option}}
*--bin* _NAME_...::
{actionverb} the specified binary. This flag may be specified multiple times.
{{#option "`--bin` _name_..." }}
{{actionverb}} the specified binary. This flag may be specified multiple times.
{{/option}}
*--bins*::
{actionverb} all binary targets.
{{#option "`--bins`" }}
{{actionverb}} all binary targets.
{{/option}}

73
src/doc/man/includes/options-targets.md
View File

@ -1,39 +1,50 @@
Passing target selection flags will convert:lowercase[{actionverb}] only the
specified targets.
Passing target selection flags will {{lower actionverb}} only the specified
targets.
include::options-targets-lib-bin.adoc[]
{{#options}}
*--example* _NAME_...::
{actionverb} the specified example. This flag may be specified multiple times.
{{> options-targets-lib-bin }}
*--examples*::
{actionverb} all example targets.
{{#option "`--example` _name_..." }}
{{actionverb}} the specified example. This flag may be specified multiple times.
{{/option}}
*--test* _NAME_...::
{actionverb} the specified integration test. This flag may be specified multiple
times.
{{#option "`--examples`" }}
{{actionverb}} all example targets.
{{/option}}
*--tests*::
{actionverb} all targets in test mode that have the `test = true` manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the `test` flag in the
manifest settings for the target.
{{#option "`--test` _name_..." }}
{{actionverb}} the specified integration test. This flag may be specified
multiple times.
{{/option}}
*--bench* _NAME_...::
{actionverb} the specified benchmark. This flag may be specified multiple times.
{{#option "`--tests`" }}
{{actionverb}} all targets in test mode that have the `test = true` manifest
flag set. By default this includes the library and binaries built as
unittests, and integration tests. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
unittest, and once as a dependency for binaries, integration tests, etc.).
Targets may be enabled or disabled by setting the `test` flag in the
manifest settings for the target.
{{/option}}
*--benches*::
{actionverb} all targets in benchmark mode that have the `bench = true`
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the `bench` flag in the
manifest settings for the target.
{{#option "`--bench` _name_..." }}
{{actionverb}} the specified benchmark. This flag may be specified multiple times.
{{/option}}
*--all-targets*::
{actionverb} all targets. This is equivalent to specifying `--lib --bins
--tests --benches --examples`.
{{#option "`--benches`" }}
{{actionverb}} all targets in benchmark mode that have the `bench = true`
manifest flag set. By default this includes the library and binaries built
as benchmarks, and bench targets. Be aware that this will also build any
required dependencies, so the lib target may be built twice (once as a
benchmark, and once as a dependency for binaries, benchmarks, etc.).
Targets may be enabled or disabled by setting the `bench` flag in the
manifest settings for the target.
{{/option}}
{{#option "`--all-targets`" }}
{{actionverb}} all targets. This is equivalent to specifying `--lib --bins
--tests --benches --examples`.
{{/option}}
{{/options}}

20
src/doc/man/includes/options-test.md
View File

@ -1,8 +1,14 @@
*--no-run*::
Compile, but don't run {nouns}.
{{#options}}
*--no-fail-fast*::
Run all {nouns} regardless of failure. Without this flag, Cargo will exit
after the first executable fails. The Rust test harness will run all
{nouns} within the executable to completion, this flag only applies to
the executable as a whole.
{{#option "`--no-run`" }}
Compile, but don't run {{nouns}}.
{{/option}}
{{#option "`--no-fail-fast`" }}
Run all {{nouns}} regardless of failure. Without this flag, Cargo will exit
after the first executable fails. The Rust test harness will run all {{nouns}}
within the executable to completion, this flag only applies to the executable
as a whole.
{{/option}}
{{/options}}

11
src/doc/man/includes/options-token.md
View File

@ -1,10 +1,11 @@
*--token* _TOKEN_::
API token to use when authenticating. This overrides the token stored in
the credentials file (which is created by man:cargo-login[1]).
+
linkcargo:reference/config.html[Cargo config] environment variables can be
{{#option "`--token` _token_" }}
API token to use when authenticating. This overrides the token stored in
the credentials file (which is created by {{man "cargo-login" 1}}).
[Cargo config](../reference/config.html) environment variables can be
used to override the tokens stored in the credentials file. The token for
crates.io may be specified with the `CARGO_REGISTRY_TOKEN` environment
variable. Tokens for other registries may be specified with environment
variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name
of the registry in all capital letters.
{{/option}}

4
src/doc/man/includes/section-environment.md
View File

@ -1,4 +1,4 @@
== ENVIRONMENT
## ENVIRONMENT
See linkcargo:reference/environment-variables.html[the reference] for
See [the reference](../reference/environment-variables.html) for
details on environment variables that Cargo reads.

9
src/doc/man/includes/section-exit-status.md
View File

@ -1,7 +1,4 @@
== Exit Status
## EXIT STATUS
0::
Cargo succeeded.
101::
Cargo failed to complete.
* `0`: Cargo succeeded.
* `101`: Cargo failed to complete.

28
src/doc/man/includes/section-features.md
View File

@ -1,4 +1,4 @@
=== Feature Selection
### Feature Selection
The feature flags allow you to control the enabled features for the "current"
package. The "current" package is the package in the current directory, or the
@ -9,15 +9,21 @@ or all features if `--all-features` is specified.
When no feature options are given, the `default` feature is activated for
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. This flag may be
specified multiple times, which enables all specified features.
{{#options}}
*--all-features*::
Activate all available features of all selected packages.
{{#option "`--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. This flag may be
specified multiple times, which enables all specified features.
{{/option}}
*--no-default-features*::
Do not activate the `default` feature of the current directory's
package.
{{#option "`--all-features`" }}
Activate all available features of all selected packages.
{{/option}}
{{#option "`--no-default-features`" }}
Do not activate the `default` feature of the current directory's package.
{{/option}}
{{/options}}

31
src/doc/man/includes/section-options-common.md
View File

@ -1,14 +1,21 @@
*+TOOLCHAIN*::
If Cargo has been installed with rustup, and the first argument to `cargo`
begins with `+`, it will be interpreted as a rustup toolchain name (such
as `+stable` or `+nightly`).
See the link:https://github.com/rust-lang/rustup/[rustup documentation]
for more information about how toolchain overrides work.
### Common Options
*-h*::
*--help*::
Prints help information.
{{#options}}
*-Z* _FLAG_...::
Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for
details.
{{#option "`+`_toolchain_"}}
If Cargo has been installed with rustup, and the first argument to `cargo`
begins with `+`, it will be interpreted as a rustup toolchain name (such
as `+stable` or `+nightly`).
See the [rustup documentation](https://github.com/rust-lang/rustup/)
for more information about how toolchain overrides work.
{{/option}}
{{#option "`-h`" "`--help`"}}
Prints help information.
{{/option}}
{{#option "`-Z` _flag_"}}
Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for details.
{{/option}}
{{/options}}

14
src/doc/man/includes/section-options-package.md
View File

@ -1,7 +1,13 @@
### Package Selection
By default, the package in the current working directory is selected. The `-p`
flag can be used to choose a different package in a workspace.
*-p* _SPEC_::
*--package* _SPEC_::
The package to convert:lowercase[{actionverb}]. See man:cargo-pkgid[1] for
the SPEC format.
{{#options}}
{{#option "`-p` _spec_" "`--package` _spec_" }}
The package to {{lower actionverb}}. See {{man "cargo-pkgid" 1}} for the SPEC
format.
{{/option}}
{{/options}}

35
src/doc/man/includes/section-package-selection.md
View File

@ -1,3 +1,5 @@
### Package Selection
By default, when no package selection options are given, the packages selected
depend on the selected manifest file (based on the current working directory if
`--manifest-path` is not given). If the manifest is the root of a workspace then
@ -9,19 +11,26 @@ The default members of a workspace can be set explicitly with the
virtual workspace will include all workspace members (equivalent to passing
`--workspace`), and a non-virtual workspace will include only the root crate itself.
*-p* _SPEC_...::
*--package* _SPEC_...::
{actionverb} only the specified packages. See man:cargo-pkgid[1] for the
SPEC format. This flag may be specified multiple times.
{{#options}}
*--workspace*::
{actionverb} all members in the workspace.
{{#option "`-p` _spec_..." "`--package` _spec_..."}}
{{actionverb}} only the specified packages. See {{man "cargo-pkgid" 1}} for the
SPEC format. This flag may be specified multiple times.
{{/option}}
ifndef::noall[]
*--all*::
Deprecated alias for `--workspace`.
endif::noall[]
{{#option "`--workspace`" }}
{{actionverb}} all members in the workspace.
{{/option}}
*--exclude* _SPEC_...::
Exclude the specified packages. Must be used in conjunction with the
`--workspace` flag. This flag may be specified multiple times.
{{#unless noall}}
{{#option "`--all`" }}
Deprecated alias for `--workspace`.
{{/option}}
{{/unless}}
{{#option "`--exclude` _SPEC_..." }}
Exclude the specified packages. Must be used in conjunction with the
`--workspace` flag. This flag may be specified multiple times.
{{/option}}
{{/options}}

24
src/doc/man/includes/section-profiles.md
View File

@ -1,26 +1,16 @@
== PROFILES
## PROFILES
Profiles may be used to configure compiler options such as optimization levels
and debug settings. See
linkcargo:reference/profiles.html[the reference]
for more details.
and debug settings. See [the reference](../reference/profiles.html) for more
details.
Profile selection depends on the target and crate being built. By default the
`dev` or `test` profiles are used. If the `--release` flag is given, then the
`release` or `bench` profiles are used.
[%autowidth]
|===
|Target |Default Profile |`--release` Profile
|lib, bin, example
|`dev`
|`release`
|test, bench, or any target +
in "test" or "bench" mode
|`test`
|`bench`
|===
Target | Default Profile | `--release` Profile
-------|-----------------|---------------------
lib, bin, example | `dev` | `release`
test, bench, or any target in "test" or "bench" mode | `test` | `bench`
Dependencies use the `dev`/`release` profiles.