diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt new file mode 100644 index 00000000000..13b4cc6ab6f --- /dev/null +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -0,0 +1,347 @@ +CARGO-BENCH(1) + +NAME + cargo-bench - Execute benchmarks of a package + +SYNOPSIS + cargo bench [options] [benchname] [-- bench-options] + +DESCRIPTION + Compile and execute benchmarks. + + 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 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): + + cargo bench -- foo --exact + + Benchmarks are built with the --test option to rustc which creates an + executable with a main function that automatically runs all functions + annotated with the #[bench] attribute. Cargo passes the --bench flag to + the test harness to tell it to run only benchmarks. + + 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 #[bench] attribute + + is currently unstable and only available on the nightly channel + . There + are some packages available on crates.io + that may help with running + benchmarks on the stable channel, such as Criterion + . + +OPTIONS + Benchmark Options + --no-run + Compile, but don't run benchmarks. + + --no-fail-fast + Run all benchmarks regardless of failure. Without this flag, Cargo + will exit after the first executable fails. The Rust test harness + will run all benchmarks within the executable to completion, this + flag only applies to the executable as a whole. + + 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 the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a 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... + Benchmark only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times. + + --workspace + Benchmark all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + Target Selection + When no target selection options are given, cargo bench will build the + following targets of the selected packages: + + o lib — used to link with binaries and benchmarks + + o bins (only if benchmark targets are built and required features are + available) + + o lib as a benchmark + + o bins as benchmarks + + o benchmark targets + + The default behavior can be changed by setting the bench flag for the + target in the manifest settings. Setting examples to bench = true will + build and run the example as a benchmark. Setting targets to bench = + false will stop 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. + + Passing target selection flags will benchmark only the specified + targets. + + --lib + Benchmark the package's library. + + --bin name... + Benchmark the specified binary. This flag may be specified multiple + times. + + --bins + Benchmark all binary targets. + + --example name... + Benchmark the specified example. This flag may be specified multiple + times. + + --examples + Benchmark all example targets. + + --test name... + Benchmark the specified integration test. This flag may be specified + multiple times. + + --tests + Benchmark 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. + + --bench name... + Benchmark the specified benchmark. This flag may be specified + multiple times. + + --benches + Benchmark 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. + + --all-targets + Benchmark all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Benchmark for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + 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 passing --nocapture to the benchmark binaries: + + cargo bench -- --nocapture + + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + for more + details. + + Benchmarks are always built with the bench profile. Binary and lib + targets are built separately as benchmarks with the bench profile. + Library targets 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 + 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. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build and execute all the benchmarks of the current package: + + cargo bench + + 2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +SEE ALSO + cargo(1), cargo-test(1) + diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt new file mode 100644 index 00000000000..2d2dd17eadd --- /dev/null +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -0,0 +1,308 @@ +CARGO-BUILD(1) + +NAME + cargo-build - Compile the current package + +SYNOPSIS + cargo build [options] + +DESCRIPTION + Compile local packages and all of their dependencies. + +OPTIONS + 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 the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a 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... + Build only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Build all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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. + + Passing target selection flags will build only the specified targets. + + --lib + Build the package's library. + + --bin name... + Build the specified binary. This flag may be specified multiple + times. + + --bins + Build all binary targets. + + --example name... + Build the specified example. This flag may be specified multiple + times. + + --examples + Build all example targets. + + --test name... + Build the specified integration test. This flag may be specified + multiple times. + + --tests + Build 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. + + --bench name... + Build the specified benchmark. This flag may be specified multiple + times. + + --benches + Build 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. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Build optimized artifacts with the release profile. See the PROFILES + section for details on how this affects profile selection. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + --out-dir directory + Copy final artifacts to this directory. + + This option is unstable and available only on the nightly channel + and + requires the -Z unstable-options flag to enable. See + https://github.com/rust-lang/cargo/issues/6790 for more information. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + --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 nightly channel + and + requires the -Z unstable-options flag to enable. See + for more + information. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package and all of its dependencies: + + cargo build + + 2. Build with optimizations: + + cargo build --release + +SEE ALSO + cargo(1), cargo-rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt new file mode 100644 index 00000000000..a2751713076 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -0,0 +1,300 @@ +CARGO-CHECK(1) + +NAME + cargo-check - Check the current package + +SYNOPSIS + cargo check [options] + +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 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 + 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 the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a 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... + Check only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Check all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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. + + Passing target selection flags will check only the specified targets. + + --lib + Check the package's library. + + --bin name... + Check the specified binary. This flag may be specified multiple + times. + + --bins + Check all binary targets. + + --example name... + Check the specified example. This flag may be specified multiple + times. + + --examples + Check all example targets. + + --test name... + Check the specified integration test. This flag may be specified + multiple times. + + --tests + Check 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. + + --bench name... + Check the specified benchmark. This flag may be specified multiple + times. + + --benches + Check 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. + + --all-targets + Check all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Check for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Check optimized artifacts with the release profile. See the PROFILES + section for details on how this affects profile selection. + + --profile name + Changes check behavior. Currently only test is supported, which will + check with the #[cfg(test)] attribute enabled. This is useful to + have it check unit tests which are usually excluded via the cfg + attribute. This does not change the actual profile used. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Check the local package for errors: + + cargo check + + 2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-clean.txt b/src/doc/man/generated_txt/cargo-clean.txt new file mode 100644 index 00000000000..4a55ae00736 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-clean.txt @@ -0,0 +1,145 @@ +CARGO-CLEAN(1) + +NAME + cargo-clean - Remove generated artifacts + +SYNOPSIS + cargo clean [options] + +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 + 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 cargo-pkgid(1) for the SPEC format. + + Clean Options + --doc + This option will cause cargo clean to remove only the doc directory + in the target directory. + + --release + Clean all artifacts that were built with the release or bench + profiles. + + --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 + . Defaults to + target in the root of the workspace. + + --target triple + Clean for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Remove the entire target directory: + + cargo clean + + 2. Remove only the release artifacts: + + cargo clean --release + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt new file mode 100644 index 00000000000..536fcbf927b --- /dev/null +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -0,0 +1,266 @@ +CARGO-DOC(1) + +NAME + cargo-doc - Build a package's documentation + +SYNOPSIS + cargo doc [options] + +DESCRIPTION + Build the documentation for the local package and all dependencies. The + output is placed in target/doc in rustdoc's usual format. + +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. + + --no-deps + Do not build documentation for dependencies. + + --document-private-items + Include non-public items in the documentation. + + 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 the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a 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... + Document only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times. + + --workspace + Document all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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 if its name is the same as the lib target. Binaries are skipped + if they have required-features that are missing. + + 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. + + --lib + Document the package's library. + + --bin name... + Document the specified binary. This flag may be specified multiple + times. + + --bins + Document all binary targets. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Document optimized artifacts with the release profile. See the + PROFILES section for details on how this affects profile selection. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package documentation and its dependencies and output + to target/doc. + + cargo doc + +SEE ALSO + cargo(1), cargo-rustdoc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-fetch.txt b/src/doc/man/generated_txt/cargo-fetch.txt new file mode 100644 index 00000000000..5deccaf1855 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fetch.txt @@ -0,0 +1,128 @@ +CARGO-FETCH(1) + +NAME + cargo-fetch - Fetch dependencies of a package from the network + +SYNOPSIS + cargo fetch [options] + +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 available. Subsequent Cargo commands never touch the network + after a cargo fetch unless the lock file changes. + + If the lock file is not available, then this command will generate the + lock file before fetching the dependencies. + + If --target is not specified, then all target dependencies are fetched. + + See also the 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 + Fetch options + --target triple + Fetch for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Fetch all dependencies: + + cargo fetch + +SEE ALSO + cargo(1), cargo-update(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt new file mode 100644 index 00000000000..b63933eec06 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -0,0 +1,354 @@ +CARGO-FIX(1) + +NAME + cargo-fix - Automatically fix lint warnings reported by rustc + +SYNOPSIS + cargo fix [options] + +DESCRIPTION + This Cargo subcommand will automatically take rustc's suggestions from + diagnostics like warnings and apply them to your source code. This is + intended to help automate tasks that rustc itself already knows how to + tell you to fix! 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 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 executing: + + cargo fix --edition + + which behaves the same as cargo check --all-targets. + + cargo fix is only capable of fixing code that is normally compiled with + cargo check. If code is conditionally enabled with optional features, + you will need to enable those features for that code to be analyzed: + + cargo fix --edition --features foo + + Similarly, other cfg expressions like platform-specific code will need + to pass --target to fix code for the given target. + + cargo fix --edition --target x86_64-pc-windows-gnu + + 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 + + +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. + + --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. + + --edition-idioms + Apply suggestions that will update code to the preferred style for + the current edition. + + --allow-no-vcs + Fix code even if a VCS was not detected. + + --allow-dirty + Fix code even if the working directory has changes. + + --allow-staged + Fix code even if the working directory has staged changes. + + 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 the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a 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... + Fix only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Fix all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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. + + Passing target selection flags will fix only the specified targets. + + --lib + Fix the package's library. + + --bin name... + Fix the specified binary. This flag may be specified multiple times. + + --bins + Fix all binary targets. + + --example name... + Fix the specified example. This flag may be specified multiple + times. + + --examples + Fix all example targets. + + --test name... + Fix the specified integration test. This flag may be specified + multiple times. + + --tests + Fix 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. + + --bench name... + Fix the specified benchmark. This flag may be specified multiple + times. + + --benches + Fix 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. + + --all-targets + Fix all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Fix for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Fix optimized artifacts with the release profile. See the PROFILES + section for details on how this affects profile selection. + + --profile name + Changes fix behavior. Currently only test is supported, which will + fix with the #[cfg(test)] attribute enabled. This is useful to have + it fix unit tests which are usually excluded via the cfg attribute. + This does not change the actual profile used. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Apply compiler suggestions to the local package: + + cargo fix + + 2. Convert a 2015 edition to 2018: + + cargo fix --edition + + 3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +SEE ALSO + cargo(1), cargo-check(1) + diff --git a/src/doc/man/generated_txt/cargo-generate-lockfile.txt b/src/doc/man/generated_txt/cargo-generate-lockfile.txt new file mode 100644 index 00000000000..5ef41c05dec --- /dev/null +++ b/src/doc/man/generated_txt/cargo-generate-lockfile.txt @@ -0,0 +1,104 @@ +CARGO-GENERATE-LOCKFILE(1) + +NAME + cargo-generate-lockfile - Generate the lockfile for a package + +SYNOPSIS + cargo generate-lockfile [options] + +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 cargo-update(1) which is also capable of creating a Cargo.lock + lockfile and has more options for controlling update behavior. + +OPTIONS + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +SEE ALSO + cargo(1), cargo-update(1) + diff --git a/src/doc/man/generated_txt/cargo-help.txt b/src/doc/man/generated_txt/cargo-help.txt new file mode 100644 index 00000000000..ea87ddfdb48 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-help.txt @@ -0,0 +1,23 @@ +CARGO-HELP(1) + +NAME + cargo-help - Get help for a Cargo command + +SYNOPSIS + cargo help [subcommand] + +DESCRIPTION + Prints a help message for the given command. + +EXAMPLES + 1. Get help for a command: + + cargo help build + + 2. Help is also available with the --help flag: + + cargo build --help + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-init.txt b/src/doc/man/generated_txt/cargo-init.txt new file mode 100644 index 00000000000..9ef78f94280 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-init.txt @@ -0,0 +1,150 @@ +CARGO-INIT(1) + +NAME + cargo-init - Create a new Cargo package in an existing directory + +SYNOPSIS + cargo init [options] [path] + +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. + + If there are typically-named Rust source files already in the directory, + those will be used. If not, then a sample src/main.rs file will be + created, or src/lib.rs if --lib is passed. + + If the directory is not already in a VCS repository, then a new + repository is created (see --vcs below). + + The "authors" field in the manifest is determined from the environment + or configuration settings. A name is required and is determined from + (first match wins): + + o cargo-new.name Cargo config value + + o CARGO_NAME environment variable + + o GIT_AUTHOR_NAME environment variable + + o GIT_COMMITTER_NAME environment variable + + o user.name git configuration value + + o USER environment variable + + o USERNAME environment variable + + o NAME environment variable + + The email address is optional and is determined from: + + o cargo-new.email Cargo config value + + o CARGO_EMAIL environment variable + + o GIT_AUTHOR_EMAIL environment variable + + o GIT_COMMITTER_EMAIL environment variable + + o user.email git configuration value + + o EMAIL environment variable + + See the reference + for more + information about configuration files. + + See cargo-new(1) for a similar command which will create a new package + in a new directory. + +OPTIONS + Init Options + --bin + Create a package with a binary target (src/main.rs). This is the + default behavior. + + --lib + Create a package with a library target (src/lib.rs). + + --edition edition + Specify the Rust edition to use. Default is 2018. Possible values: + 2015, 2018 + + --name name + Set the package name. Defaults to the directory name. + + --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. + + --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 + . 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. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the current directory: + + cargo init + +SEE ALSO + cargo(1), cargo-new(1) + diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt new file mode 100644 index 00000000000..f02a8b23ece --- /dev/null +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -0,0 +1,298 @@ +CARGO-INSTALL(1) + +NAME + cargo-install - Build and install a Rust binary + +SYNOPSIS + cargo install [options] crate... + cargo install [options] --path path + cargo install [options] --git url [crate...] + cargo install [options] --list + +DESCRIPTION + This command manages Cargo's local set of installed binary crates. Only + packages which have executable [[bin]] or [[example]] targets can be + installed, and all executables are installed into the installation + root's bin folder. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + + + o CARGO_HOME environment variable + + o $HOME/.cargo + + 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 required to indicate which crate should be installed. + + Crates from crates.io can optionally specify the version they wish to + install via the --version flags, and similarly packages from git + repositories can optionally specify the branch, tag, or revision that + should be installed. If a crate has multiple binaries, the --bin + argument can selectively install only one of them, and if you'd rather + install examples the --example argument can be used as well. + + If the package is already installed, Cargo will reinstall it if the + installed version does not appear to be up-to-date. If any of the + following values change, then Cargo will reinstall the package: + + o The package version and source. + + o The set of binary names installed. + + o The chosen features. + + o The release mode (--debug). + + o The target (--target). + + Installing with --path will always build and install, unless there are + conflicting binaries from another package. The --force flag may be used + to force Cargo to always reinstall the package. + + If the source is crates.io or --git then by default the crate will be + built in a temporary target directory. To avoid this, the target + directory can be specified by setting the CARGO_TARGET_DIR environment + variable to a relative path. In particular, this can be useful for + caching build artifacts on continuous integration systems. + + By default, the Cargo.lock file that is included with the package will + be ignored. This means that Cargo will recompute which versions of + dependencies to use, possibly using newer versions that have been + released since the package was published. The --locked flag can be used + to force Cargo to use the packaged Cargo.lock file if it is available. + This may be useful for ensuring reproducible builds, to use the exact + same set of dependencies that were available when the package was + published. It may also be useful if a newer version of a dependency is + published that no longer builds on your system, or has other problems. + The downside to using --locked is that you will not receive any fixes or + updates to any dependency. Note that Cargo did 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 + Install Options + --vers version, --version version + Specify a version to install. This may be a 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. + + --git url + Git URL to install the specified crate from. + + --branch branch + Branch to use when installing from git. + + --tag tag + Tag to use when installing from git. + + --rev sha + Specific commit to use when installing from git. + + --path path + Filesystem path to local crate to install. + + --list + List all installed packages and their versions. + + -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. + + --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. + + --bin name... + Install only the specified binary. + + --bins + Install all binaries. + + --example name... + Install only the specified example. + + --examples + Install all examples. + + --root dir + Directory to install packages into. + + --registry registry + Name of the registry to use. Registry names are defined in 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. + + --index index + The URL of the registry index to use. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Install for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --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 + . Defaults to + target in the root of the workspace. + + --debug + Build with the dev profile instead the release profile. + + Manifest Options + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Install or upgrade a package from crates.io: + + cargo install ripgrep + + 2. Install or reinstall the package in the current directory: + + cargo install --path . + + 3. View the list of installed packages: + + cargo install --list + +SEE ALSO + cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-locate-project.txt b/src/doc/man/generated_txt/cargo-locate-project.txt new file mode 100644 index 00000000000..ec1377fb568 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-locate-project.txt @@ -0,0 +1,78 @@ +CARGO-LOCATE-PROJECT(1) + +NAME + cargo-locate-project - Print a JSON representation of a Cargo.toml + file's location + +SYNOPSIS + cargo locate-project [options] + +DESCRIPTION + This command will print a JSON object to stdout with the full path to + the Cargo.toml manifest. + + See also cargo-metadata(1) which is capable of returning the path to a + workspace root. + +OPTIONS + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the path to the manifest based on the current directory: + + cargo locate-project + +SEE ALSO + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-login.txt b/src/doc/man/generated_txt/cargo-login.txt new file mode 100644 index 00000000000..447c32c002f --- /dev/null +++ b/src/doc/man/generated_txt/cargo-login.txt @@ -0,0 +1,87 @@ +CARGO-LOGIN(1) + +NAME + cargo-login - Save an API token from the registry locally + +SYNOPSIS + cargo login [options] [token] + +DESCRIPTION + This command will save the API token to disk so that commands that + require authentication, such as 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. + + The API token for crates.io may be retrieved from + . + + Take care to keep the token secret, it should not be shared with anyone + else. + +OPTIONS + Login Options + --registry registry + Name of the registry to use. Registry names are defined in 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. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Save the API token to disk: + + cargo login + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt new file mode 100644 index 00000000000..5ecd04f4445 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-metadata.txt @@ -0,0 +1,407 @@ +CARGO-METADATA(1) + +:source-highlighter: highlightjs + +NAME + cargo-metadata - Machine-readable metadata about the current package + +SYNOPSIS + cargo metadata [options] + +DESCRIPTION + Output JSON to stdout containing information about the workspace members + and 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 cargo_metadata crate + for a Rust API for reading the metadata. + +OUTPUT FORMAT + The output has the following format: + + { + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* A string of the URL of the registry this dependency is from. + If not specified or null, the dependency is from the default + registry (crates.io). + */ + "registry": null + } + ], + /* Array of Cargo targets. */ + "targets": [ + { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "bin" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "bin" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/main.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": false, + /* Whether or not this target should be built and run with `--test` + */ + "test": true + } + ], + /* Set of features defined for the package. + Each feature maps to an array of features or dependencies it + enables. + */ + "features": { + "default": [ + "feat1" + ], + "feat1": [], + "feat2": [] + }, + /* Absolute path to this package's manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* Package metadata. + This is null if no metadata is specified. + */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + }, + /* List of registries to which this package may be published. + Publishing is unrestricted if null, and forbidden if an empty array. */ + "publish": [ + "crates-io" + ], + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe " + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018", + /* Optional string that is the name of a native library the package + is linking to. + */ + "links": null, + } + ], + /* Array of members of the workspace. + Each entry is the Package ID for the package. + */ + "workspace_members": [ + "my-package 0.1.0 (path+file:///path/to/my-package)", + ], + // The resolved dependency graph for the entire workspace. The enabled + // features are based on the enabled features for the "current" package. + // Inactivated optional dependencies are not listed. + // + // This is null if --no-deps is specified. + // + // By default, this includes all dependencies for all target platforms. + // The `--filter-platform` flag may be used to narrow to a specific + // target triple. + "resolve": { + /* Array of nodes within the dependency graph. + Each node is a package. + */ + "nodes": [ + { + /* The Package ID of this node. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The dependencies of this package, an array of Package IDs. */ + "dependencies": [ + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" + ], + /* The dependencies of this package. This is an alternative to + "dependencies" which contains additional information. In + particular, this handles renamed dependencies. + */ + "deps": [ + { + /* The name of the dependency's library target. + If this is a renamed dependency, this is the new + name. + */ + "name": "bitflags", + /* The Package ID of the dependency. */ + "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + /* Array of dependency kinds. Added in Cargo 1.40. */ + "dep_kinds": [ + { + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)" + } + ] + } + ], + /* Array of features enabled on this package. */ + "features": [ + "default" + ] + } + ], + /* The root package of the workspace. + This is null if this is a virtual workspace. Otherwise it is + the Package ID of the root package. + */ + "root": "my-package 0.1.0 (path+file:///path/to/my-package)" + }, + /* The absolute path to the build directory where Cargo places its output. */ + "target_directory": "/path/to/my-package/target", + /* The version of the schema for this metadata structure. + This will be changed if incompatible changes are ever made. + */ + "version": 1, + /* The absolute path to the root of the workspace. */ + "workspace_root": "/path/to/my-package" + /* Workspace metadata. + This is null if no metadata is specified. */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + } + } + +OPTIONS + Output Options + --no-deps + Output information only about the workspace members and don't fetch + dependencies. + + --format-version version + Specify the version of the output format to use. Currently 1 is the + only possible value. + + --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. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Output JSON about the current package: + + cargo metadata --format-version=1 + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-new.txt b/src/doc/man/generated_txt/cargo-new.txt new file mode 100644 index 00000000000..241db365829 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-new.txt @@ -0,0 +1,145 @@ +CARGO-NEW(1) + +NAME + cargo-new - Create a new Cargo package + +SYNOPSIS + cargo new [options] path + +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). + + The "authors" field in the manifest is determined from the environment + or configuration settings. A name is required and is determined from + (first match wins): + + o cargo-new.name Cargo config value + + o CARGO_NAME environment variable + + o GIT_AUTHOR_NAME environment variable + + o GIT_COMMITTER_NAME environment variable + + o user.name git configuration value + + o USER environment variable + + o USERNAME environment variable + + o NAME environment variable + + The email address is optional and is determined from: + + o cargo-new.email Cargo config value + + o CARGO_EMAIL environment variable + + o GIT_AUTHOR_EMAIL environment variable + + o GIT_COMMITTER_EMAIL environment variable + + o user.email git configuration value + + o EMAIL environment variable + + See the reference + for more + information about configuration files. + + See cargo-init(1) for a similar command which will create a new manifest + in an existing directory. + +OPTIONS + New Options + --bin + Create a package with a binary target (src/main.rs). This is the + default behavior. + + --lib + Create a package with a library target (src/lib.rs). + + --edition edition + Specify the Rust edition to use. Default is 2018. Possible values: + 2015, 2018 + + --name name + Set the package name. Defaults to the directory name. + + --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. + + --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 + . 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. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the given directory: + + cargo new foo + +SEE ALSO + cargo(1), cargo-init(1) + diff --git a/src/doc/man/generated_txt/cargo-owner.txt b/src/doc/man/generated_txt/cargo-owner.txt new file mode 100644 index 00000000000..65128529651 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-owner.txt @@ -0,0 +1,122 @@ +CARGO-OWNER(1) + +NAME + cargo-owner - Manage the owners of a crate on the registry + +SYNOPSIS + cargo owner [options] --add login [crate] + cargo owner [options] --remove login [crate] + cargo owner [options] --list [crate] + +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 cargo-login(1). + + If the crate name is not specified, it will use the package name from + the current directory. + + See the reference + + for more information about owners and publishing. + +OPTIONS + Owner Options + -a, --add login... + Invite the given user or team as an owner. + + -r, --remove login... + Remove the given user or team as an owner. + + -l, --list + List owners of a crate. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config + 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. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in 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. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. List owners of a package: + + cargo owner --list foo + + 2. Invite an owner to a package: + + cargo owner --add username foo + + 3. Remove an owner from a package: + + cargo owner --remove username foo + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-package.txt b/src/doc/man/generated_txt/cargo-package.txt new file mode 100644 index 00000000000..2e82404c2eb --- /dev/null +++ b/src/doc/man/generated_txt/cargo-package.txt @@ -0,0 +1,204 @@ +CARGO-PACKAGE(1) + +NAME + cargo-package - Assemble the local package into a distributable tarball + +SYNOPSIS + cargo package [options] + +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: + + 1. Load and check the current workspace, performing some basic checks. + o 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. + + 2. Create the compressed .crate file. + o The original Cargo.toml file is rewritten and normalized. + + o [patch], [replace], and [workspace] sections are removed from the + manifest. + + o Cargo.lock is automatically included if the package contains an + executable binary or example target. cargo-install(1) will use the + packaged lock file if the --locked flag is used. + + o A .cargo_vcs_info.json file is included that contains information + about the current VCS checkout hash if available (not included + with --allow-dirty). + + 3. Extract the .crate file and build it to verify it can build. + o 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. + + 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 the reference + for more + details about packaging and publishing. + +OPTIONS + Package Options + -l, --list + Print files included in a package without making one. + + --no-verify + Don't verify the contents by building them. + + --no-metadata + Ignore warnings about a lack of human-usable metadata (such as the + description or the license). + + --allow-dirty + Allow working directories with uncommitted VCS changes to be + packaged. + + Compilation Options + --target triple + Package for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --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 + . Defaults to + target in the root of the workspace. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a compressed .crate file of the current package: + + cargo package + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-pkgid.txt b/src/doc/man/generated_txt/cargo-pkgid.txt new file mode 100644 index 00000000000..01a910d0378 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-pkgid.txt @@ -0,0 +1,142 @@ +CARGO-PKGID(1) + +NAME + cargo-pkgid - Print a fully qualified package specification + +SYNOPSIS + cargo pkgid [options] [spec] + +DESCRIPTION + 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 package is printed. + + This command requires that a lockfile is available and dependencies have + been 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 following: + + +-----------------+--------------------------------------------------+ + | 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 | + +-----------------+--------------------------------------------------+ + +OPTIONS + Package Selection + -p spec, --package spec + Get the package ID for the given package instead of the current + package. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Retrieve package specification for foo package: + + cargo pkgid foo + + 2. Retrieve package specification for version 1.0.0 of foo: + + cargo pkgid foo:1.0.0 + + 3. Retrieve package specification for foo from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +SEE ALSO + cargo(1), cargo-generate-lockfile(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-publish.txt b/src/doc/man/generated_txt/cargo-publish.txt new file mode 100644 index 00000000000..ed9234a984a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-publish.txt @@ -0,0 +1,205 @@ +CARGO-PUBLISH(1) + +NAME + cargo-publish - Upload a package to the registry + +SYNOPSIS + cargo publish [options] + +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 . This performs + the following steps: + + 1. Performs a few checks, including: + o 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 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 cargo-login(1). + + See the reference + for more + details about packaging and publishing. + +OPTIONS + Publish Options + --dry-run + Perform all checks without uploading. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config + 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. + + --no-verify + Don't verify the contents by building them. + + --allow-dirty + Allow working directories with uncommitted VCS changes to be + packaged. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in 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. + + Compilation Options + --target triple + Publish for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --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 + . Defaults to + target in the root of the workspace. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Publish the current package: + + cargo publish + +SEE ALSO + cargo(1), cargo-package(1), cargo-login(1) + diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt new file mode 100644 index 00000000000..4bb9dbf4b49 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -0,0 +1,233 @@ +CARGO-RUN(1) + +NAME + cargo-run - Run the current package + +SYNOPSIS + cargo run [options] [-- args] + +DESCRIPTION + Run a binary or example of the local package. + + 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 + 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 run. See cargo-pkgid(1) for the SPEC format. + + 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. + + --example name + Run the specified example. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Run for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Run optimized artifacts with the release profile. See the PROFILES + section for details on how this affects profile selection. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +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 + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt new file mode 100644 index 00000000000..7061abd0fbf --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -0,0 +1,290 @@ +CARGO-RUSTC(1) + +NAME + cargo-rustc - Compile the current package, and pass extra options to the + compiler + +SYNOPSIS + cargo rustc [options] [-- args] + +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 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. + + See for documentation on + rustc flags. + + This command requires that only one target is being compiled when + additional arguments are provided. If more than one target is available + for the current package the filters of --lib, --bin, etc, must be used + to select which target is compiled. + + To pass flags to all compiler processes spawned by Cargo, use the + RUSTFLAGS environment variable + + or the build.rustflags config value + . + +OPTIONS + 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 build. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo rustc will build all + binary and library targets of the selected package. + + Passing target selection flags will build only the specified targets. + + --lib + Build the package's library. + + --bin name... + Build the specified binary. This flag may be specified multiple + times. + + --bins + Build all binary targets. + + --example name... + Build the specified example. This flag may be specified multiple + times. + + --examples + Build all example targets. + + --test name... + Build the specified integration test. This flag may be specified + multiple times. + + --tests + Build 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. + + --bench name... + Build the specified benchmark. This flag may be specified multiple + times. + + --benches + Build 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. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Build optimized artifacts with the release profile. See the PROFILES + section for details on how this affects profile selection. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +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 + cargo(1), cargo-build(1), rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt new file mode 100644 index 00000000000..bbf63d01d64 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -0,0 +1,292 @@ +CARGO-RUSTDOC(1) + +NAME + cargo-rustdoc - Build a package's documentation, using specified custom + flags + +SYNOPSIS + cargo rustdoc [options] [-- args] + +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 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 be added to the rustdoc invocation. + + See for documentation on + rustdoc flags. + + This command requires that only one target is being compiled when + additional arguments are provided. If more than one target is available + for the current package the filters of --lib, --bin, etc, must be used + to select which target is compiled. + + To pass flags to all rustdoc processes spawned by Cargo, use the + RUSTDOCFLAGS environment variable + + or the build.rustdocflags config value + . + +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. + + 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 document. See cargo-pkgid(1) for the SPEC format. + + 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. + + Passing target selection flags will document only the specified targets. + + --lib + Document the package's library. + + --bin name... + Document the specified binary. This flag may be specified multiple + times. + + --bins + Document all binary targets. + + --example name... + Document the specified example. This flag may be specified multiple + times. + + --examples + Document all example targets. + + --test name... + Document the specified integration test. This flag may be specified + multiple times. + + --tests + Document 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. + + --bench name... + Document the specified benchmark. This flag may be specified + multiple times. + + --benches + Document 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. + + --all-targets + Document all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Document optimized artifacts with the release profile. See the + PROFILES section for details on how this affects profile selection. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +SEE ALSO + cargo(1), cargo-doc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-search.txt b/src/doc/man/generated_txt/cargo-search.txt new file mode 100644 index 00000000000..eb3446dfb43 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-search.txt @@ -0,0 +1,84 @@ +CARGO-SEARCH(1) + +NAME + cargo-search - Search packages in crates.io + +SYNOPSIS + cargo search [options] [query...] + +DESCRIPTION + This performs a textual search for crates on . The + matching crates will be displayed along with their description in TOML + format suitable for copying into a Cargo.toml manifest. + +OPTIONS + Search Options + --limit limit + Limit the number of results (default: 10, max: 100). + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in 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. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Search for a package from crates.io: + + cargo search serde + +SEE ALSO + cargo(1), cargo-install(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt new file mode 100644 index 00000000000..ad6ac27b98e --- /dev/null +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -0,0 +1,389 @@ +CARGO-TEST(1) + +NAME + cargo-test - Execute unit and integration tests of a package + +SYNOPSIS + cargo test [options] [testname] [-- test-options] + +DESCRIPTION + Compile and execute unit and integration tests. + + The test filtering argument TESTNAME and all the arguments following the + two 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. + + As an example, this will filter for tests with foo in their name and run + them on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + + 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 functions will also be run with one iteration to verify that + they are functional. + + 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 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 rustdoc book + for more information on writing doc tests. + +OPTIONS + Test Options + --no-run + Compile, but don't run tests. + + --no-fail-fast + Run all tests regardless of failure. Without this flag, Cargo will + exit after the first executable fails. The Rust test harness will + run all tests within the executable to completion, this flag only + applies to the executable as a whole. + + 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 the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a 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... + Test only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Test all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + Target Selection + When no target selection options are given, cargo test will build the + following targets of the selected packages: + + o lib — used to link with binaries, examples, integration tests, and + doc tests + + o bins (only if integration tests are built and required features are + available) + + o examples — to ensure they compile + + o lib as a unit test + + o bins as unit tests + + o integration tests + + o doc tests for the lib target + + The default behavior can be changed by setting the test flag for the + target in the manifest settings. Setting examples to test = true will + build and run the example as a test. Setting targets to test = false + will stop them from being tested by default. Target selection options + that take a target by name ignore the test flag and will always test the + given target. + + Doc tests for libraries may be disabled by setting doctest = false for + the 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_ environment + variable + + is set when the integration test is built so that it can use the env + macro to locate the + executable. + + Passing target selection flags will test only the specified targets. + + --lib + Test the package's library. + + --bin name... + Test the specified binary. This flag may be specified multiple + times. + + --bins + Test all binary targets. + + --example name... + Test the specified example. This flag may be specified multiple + times. + + --examples + Test all example targets. + + --test name... + Test the specified integration test. This flag may be specified + multiple times. + + --tests + Test 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. + + --bench name... + Test the specified benchmark. This flag may be specified multiple + times. + + --benches + Test 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. + + --all-targets + Test all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + --doc + Test only the library's documentation. This cannot be mixed with + other target options. + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Test for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Test optimized artifacts with the release profile. See the PROFILES + section for details on how this affects profile selection. + + Output Options + --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 + . Defaults to + target in the root of the workspace. + + 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 --nocapture to the test binaries: + + cargo test -- --nocapture + + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in 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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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 includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + . Defaults to + the number of CPUs. + +PROFILES + Profiles may be used to configure compiler options such as optimization + levels and debug settings. See the reference + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release 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 dev/release profiles) unless you are building them with the test + harness (by setting test = true in the manifest or using the --example + flag) in 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. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Execute all the unit and integration tests of the current package: + + cargo test + + 2. Run only tests whose names match against a filter string: + + cargo test name_filter + + 3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +SEE ALSO + cargo(1), cargo-bench(1) + diff --git a/src/doc/man/generated_txt/cargo-tree.txt b/src/doc/man/generated_txt/cargo-tree.txt new file mode 100644 index 00000000000..d0a3828c4ed --- /dev/null +++ b/src/doc/man/generated_txt/cargo-tree.txt @@ -0,0 +1,332 @@ +CARGO-TREE(1) + +NAME + cargo-tree - Display a tree visualization of a dependency graph + +SYNOPSIS + cargo tree [options] + +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 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── 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 repeated. Use the --no-dedupe option to repeat the duplicates. + + 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 + Tree Options + -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. + + --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. + + -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. + + -e kinds, --edges kinds + The dependency kinds to display. Takes a comma separated list of + values: + + o all — Show all edge kinds. + + o normal — Show normal dependencies. + + o build — Show build dependencies. + + o dev — Show development dependencies. + + o features — Show features enabled by each dependency. If this is + the only kind given, then it will automatically include the other + dependency kinds. + + o no-normal — Do not include normal dependencies. + + o no-build — Do not include build dependencies. + + o 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. + + --target triple + Filter dependencies matching the given target-triple. The default is + the host platform. Use the value all to include all targets. + + Tree Formatting Options + --charset charset + Chooses the character set to use for the tree. Valid values are + "utf8" or "ascii". Default is "utf8". + + -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: + + o {p} — The package name. + + o {l} — The package license. + + o {r} — The package repository URL. + + o {f} — Comma-separated list of package features that are + enabled. + + --prefix prefix + Sets how each line is displayed. The prefix value can be one of: + + o indent (default) — Shows each line indented as a tree. + + o depth — Show as a list, with the numeric depth printed before + each entry. + + o none — Show as a flat list. + + 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 the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a 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... + Display only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Display all members in the workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + 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 one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, 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 / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the tree for the package in the current directory: + + cargo tree + + 2. Display all the packages that depend on the syn package: + + cargo tree -i syn + + 3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + + 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 + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-uninstall.txt b/src/doc/man/generated_txt/cargo-uninstall.txt new file mode 100644 index 00000000000..47d4ec29f6e --- /dev/null +++ b/src/doc/man/generated_txt/cargo-uninstall.txt @@ -0,0 +1,96 @@ +CARGO-UNINSTALL(1) + +NAME + cargo-uninstall - Remove a Rust binary + +SYNOPSIS + cargo uninstall [options] [spec...] + +DESCRIPTION + This command removes a package installed with cargo-install(1). The spec + argument is a package ID specification of the package to remove (see + 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. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + + + o CARGO_HOME environment variable + + o $HOME/.cargo + +OPTIONS + Install Options + -p, --package spec... + Package to uninstall. + + --bin name... + Only uninstall the binary name. + + --root dir + Directory to uninstall packages from. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +SEE ALSO + cargo(1), cargo-install(1) + diff --git a/src/doc/man/generated_txt/cargo-update.txt b/src/doc/man/generated_txt/cargo-update.txt new file mode 100644 index 00000000000..0088515fea8 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-update.txt @@ -0,0 +1,137 @@ +CARGO-UPDATE(1) + +NAME + cargo-update - Update dependencies as recorded in the local lock file + +SYNOPSIS + cargo update [options] + +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 cargo-build(1) or + cargo-generate-lockfile(1). + +OPTIONS + Update Options + -p spec..., --package spec... + Update only the specified packages. This flag may be specified + multiple times. See 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. + + --aggressive + When used with -p, dependencies of spec are forced to update as + well. Cannot be used with --precise. + + --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). + + --dry-run + Displays what would be updated, but doesn't actually write the + lockfile. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Update all dependencies in the lockfile: + + cargo update + + 2. Update only specific dependencies: + + cargo update -p foo -p bar + + 3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +SEE ALSO + cargo(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-vendor.txt b/src/doc/man/generated_txt/cargo-vendor.txt new file mode 100644 index 00000000000..c5204a05433 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-vendor.txt @@ -0,0 +1,137 @@ +CARGO-VENDOR(1) + +NAME + cargo-vendor - Vendor all dependencies locally + +SYNOPSIS + cargo vendor [options] [path] + +DESCRIPTION + This cargo subcommand will vendor all crates.io and git dependencies for + a project into the specified directory at . After this command + completes the vendor directory specified by will contain all + remote sources from dependencies specified. Additional manifests beyond + the default one can be 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 + Vendor Options + -s manifest, --sync manifest + Specify extra Cargo.toml manifests to workspaces which should also + be vendored and synced to the output. + + --no-delete + Don't delete the "vendor" directory when vendoring, but rather keep + all existing contents of the vendor directory + + --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 + + --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. + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Vendor all dependencies into a local "vendor" folder + + 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 + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-verify-project.txt b/src/doc/man/generated_txt/cargo-verify-project.txt new file mode 100644 index 00000000000..cfd854bfd63 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-verify-project.txt @@ -0,0 +1,107 @@ +CARGO-VERIFY-PROJECT(1) + +NAME + cargo-verify-project - Check correctness of crate manifest + +SYNOPSIS + cargo verify-project [options] + +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: + + {"success":"true"} + + An invalid workspace will display: + + {"invalid":"human-readable error message"} + +OPTIONS + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: The workspace is OK. + + o 1: The workspace is invalid. + +EXAMPLES + 1. Check the current workspace for errors: + + cargo verify-project + +SEE ALSO + cargo(1), cargo-package(1) + diff --git a/src/doc/man/generated_txt/cargo-version.txt b/src/doc/man/generated_txt/cargo-version.txt new file mode 100644 index 00000000000..fc26df72579 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-version.txt @@ -0,0 +1,32 @@ +CARGO-VERSION(1) + +NAME + cargo-version - Show version information + +SYNOPSIS + cargo version [options] + +DESCRIPTION + Displays the version of Cargo. + +OPTIONS + -v, --verbose + Display additional version information. + +EXAMPLES + 1. Display the version: + + cargo version + + 2. The version is also available via flags: + + cargo --version + cargo -V + + 3. Display extra version information: + + cargo -Vv + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-yank.txt b/src/doc/man/generated_txt/cargo-yank.txt new file mode 100644 index 00000000000..eff7d9391b9 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-yank.txt @@ -0,0 +1,109 @@ +CARGO-YANK(1) + +NAME + cargo-yank - Remove a pushed crate from the index + +SYNOPSIS + cargo yank [options] --vers version [crate] + +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 still be available for download via the registry's download link. + + Note that existing crates locked to a yanked version will still be able + to 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 cargo-login(1). + + If the crate name is not specified, it will use the package name from + the current directory. + +OPTIONS + Yank Options + --vers version + The version to yank or un-yank. + + --undo + Undo a yank, putting a version back into the index. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config + 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. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in 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. + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Yank a crate from the index: + + cargo yank --vers 1.0.7 foo + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo.txt b/src/doc/man/generated_txt/cargo.txt new file mode 100644 index 00000000000..5925b562a8a --- /dev/null +++ b/src/doc/man/generated_txt/cargo.txt @@ -0,0 +1,270 @@ +CARGO(1) + +NAME + cargo - The Rust package manager + +SYNOPSIS + cargo [options] command [args] + cargo [options] --version + cargo [options] --list + cargo [options] --help + cargo [options] --explain code + +DESCRIPTION + This program is a package manager and build tool for the Rust language, + available at . + +COMMANDS + Build Commands + cargo-bench(1) +     Execute benchmarks of a package. + + cargo-build(1) +     Compile a package. + + cargo-check(1) +     Check a local package and all of its dependencies for errors. + + cargo-clean(1) +     Remove artifacts that Cargo has generated in the past. + + cargo-doc(1) +     Build a package's documentation. + + cargo-fetch(1) +     Fetch dependencies of a package from the network. + + cargo-fix(1) +     Automatically fix lint warnings reported by rustc. + + cargo-run(1) +     Run a binary or example of the local package. + + cargo-rustc(1) +     Compile a package, and pass extra options to the compiler. + + cargo-rustdoc(1) +     Build a package's documentation, using specified custom flags. + + cargo-test(1) +     Execute unit and integration tests of a package. + + Manifest Commands + cargo-generate-lockfile(1) +     Generate Cargo.lock for a project. + + cargo-locate-project(1) +     Print a JSON representation of a Cargo.toml file's location. + + cargo-metadata(1) +     Output the resolved dependencies of a package in + machine-readable format. + + cargo-pkgid(1) +     Print a fully qualified package specification. + + cargo-tree(1) +     Display a tree visualization of a dependency graph. + + cargo-update(1) +     Update dependencies as recorded in the local lock file. + + cargo-vendor(1) +     Vendor all dependencies locally. + + cargo-verify-project(1) +     Check correctness of crate manifest. + + Package Commands + cargo-init(1) +     Create a new Cargo package in an existing directory. + + cargo-install(1) +     Build and install a Rust binary. + + cargo-new(1) +     Create a new Cargo package. + + cargo-search(1) +     Search packages in crates.io. + + cargo-uninstall(1) +     Remove a Rust binary. + + Publishing Commands + cargo-login(1) +     Save an API token from the registry locally. + + cargo-owner(1) +     Manage the owners of a crate on the registry. + + cargo-package(1) +     Assemble the local package into a distributable tarball. + + cargo-publish(1) +     Upload a package to the registry. + + cargo-yank(1) +     Remove a pushed crate from the index. + + General Commands + cargo-help(1) +     Display help information about Cargo. + + cargo-version(1) +     Show version information. + +OPTIONS + Special Options + -V, --version + Print version info and exit. If used with --verbose, prints extra + information. + + --list + List all installed Cargo subcommands. If used with --verbose, prints + extra information. + + --explain code + Run rustc --explain CODE which will print out a detailed explanation + of an error message (for example, E0004). + + Display Options + -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 . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --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. + + --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 cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +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 + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +FILES + ~/.cargo/ +     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/bin/ +     Binaries installed by cargo-install(1) will be located here. If + using rustup, executables distributed with Rust are also located here. + + $CARGO_HOME/config.toml +     The global configuration file. See the reference + for more + information about configuration 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_HOME/credentials.toml +     Private authentication information for logging in to a registry. + + $CARGO_HOME/registry/ +     This directory contains cached downloads of the registry index + and any downloaded dependencies. + + $CARGO_HOME/git/ +     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 + 1. Build a local package and all of its dependencies: + + cargo build + + 2. Build a package with optimizations: + + cargo build --release + + 3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + + 4. Create a new package that builds an executable: + + cargo new foobar + + 5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + + 6. Learn about a command's options and usage: + + cargo help clean + +BUGS + See for issues. + +SEE ALSO + rustc(1), rustdoc(1) + diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index e840cbf6a2d..196e0b7e8f2 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -1,3 +1,423 @@ -# cargo bench -{{#include command-common.html}} -{{#include ../../man/generated/cargo-bench.html}} +# cargo-bench(1) + + + +## NAME + +cargo-bench - Execute benchmarks of a package + +## SYNOPSIS + +`cargo bench` [_options_] [_benchname_] [`--` _bench-options_] + +## DESCRIPTION + +Compile and execute benchmarks. + +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 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`): + + cargo bench -- foo --exact + +Benchmarks are built with the `--test` option to `rustc` which creates an +executable with a `main` function that automatically runs all functions +annotated with the `#[bench]` attribute. Cargo passes the `--bench` flag to +the test harness to tell it to run only benchmarks. + +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 +> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html) +> is currently unstable and only available on the +> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html). +> There are some packages available on +> [crates.io](https://crates.io/keywords/benchmark) that may help with +> running benchmarks on the stable channel, such as +> [Criterion](https://crates.io/crates/criterion). + +## OPTIONS + +### Benchmark Options + +
+ +
--no-run
+
Compile, but don't run benchmarks.
+ + +
--no-fail-fast
+
Run all benchmarks regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all benchmarks +within the executable to completion, this flag only applies to the executable +as a whole.
+ + +
+ + +### 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 +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +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...
+
Benchmark only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Benchmark all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### Target Selection + +When no target selection options are given, `cargo bench` will build the +following targets of the selected packages: + +- lib — used to link with binaries and benchmarks +- bins (only if benchmark targets are built and required features are + available) +- lib as a benchmark +- bins as benchmarks +- benchmark targets + +The default behavior can be changed by setting the `bench` flag for the target +in the manifest settings. Setting examples to `bench = true` will build and +run the example as a benchmark. Setting targets to `bench = false` will stop +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. + +Passing target selection flags will benchmark only the specified +targets. + +
+ +
--lib
+
Benchmark the package's library.
+ + +
--bin name...
+
Benchmark the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Benchmark all binary targets.
+ + + +
--example name...
+
Benchmark the specified example. This flag may be specified multiple times.
+ + +
--examples
+
Benchmark all example targets.
+ + +
--test name...
+
Benchmark the specified integration test. This flag may be specified +multiple times.
+ + +
--tests
+
Benchmark 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.
+ + +
--bench name...
+
Benchmark the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Benchmark 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.
+ + +
--all-targets
+
Benchmark all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Benchmark 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### 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 +passing `--nocapture` to the benchmark binaries: + + cargo bench -- --nocapture + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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. + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +[the reference](../reference/profiles.html) +for more details. + +Benchmarks are always built with the `bench` profile. Binary and lib targets +are built separately as benchmarks with the `bench` profile. Library targets +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 +[cargo-build(1)](cargo-build.md) which will use the `test` profile which is by default +unoptimized and includes debug information. You can then run the debug-enabled +benchmark manually. + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build and execute all the benchmarks of the current package: + + cargo bench + +2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-test(1)](cargo-test.md) diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index dd46f23ed39..e65d9f22742 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -1,3 +1,376 @@ -# cargo build -{{#include command-common.html}} -{{#include ../../man/generated/cargo-build.html}} +# cargo-build(1) + + +## NAME + +cargo-build - Compile the current package + +## SYNOPSIS + +`cargo build` [_options_] + +## DESCRIPTION + +Compile local packages and all of their dependencies. + +## OPTIONS + +### 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 +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +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...
+
Build only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Build all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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. + +Passing target selection flags will build only the specified +targets. + +
+ +
--lib
+
Build the package's library.
+ + +
--bin name...
+
Build the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Build all binary targets.
+ + + +
--example name...
+
Build the specified example. This flag may be specified multiple times.
+ + +
--examples
+
Build all example targets.
+ + +
--test name...
+
Build the specified integration test. This flag may be specified +multiple times.
+ + +
--tests
+
Build 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.
+ + +
--bench name...
+
Build the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Build 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.
+ + +
--all-targets
+
Build all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Build 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Build optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + + +
--out-dir directory
+
Copy final artifacts to this directory.

+

This option is unstable and available only on the +nightly channel +and requires the -Z unstable-options flag to enable. +See https://github.com/rust-lang/cargo/issues/6790 for more information.

+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + + +
--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 +nightly channel +and requires the -Z unstable-options flag to enable. +See https://github.com/rust-lang/cargo/issues/5579 for more information.

+ +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build the local package and all of its dependencies: + + cargo build + +2. Build with optimizations: + + cargo build --release + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-rustc(1)](cargo-rustc.md) diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index 473d00afe2d..4f66e977d97 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -1,3 +1,371 @@ -# cargo check -{{#include command-common.html}} -{{#include ../../man/generated/cargo-check.html}} +# cargo-check(1) + + +## NAME + +cargo-check - Check the current package + +## SYNOPSIS + +`cargo check` [_options_] + +## 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 +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 + +### 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 +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +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...
+
Check only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Check all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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. + +Passing target selection flags will check only the specified +targets. + +
+ +
--lib
+
Check the package's library.
+ + +
--bin name...
+
Check the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Check all binary targets.
+ + + +
--example name...
+
Check the specified example. This flag may be specified multiple times.
+ + +
--examples
+
Check all example targets.
+ + +
--test name...
+
Check the specified integration test. This flag may be specified +multiple times.
+ + +
--tests
+
Check 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.
+ + +
--bench name...
+
Check the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Check 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.
+ + +
--all-targets
+
Check all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Check 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Check optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
--profile name
+
Changes check behavior. Currently only test is supported, +which will check with the #[cfg(test)] attribute enabled. +This is useful to have it check unit tests which are usually +excluded via the cfg attribute. This does not change the actual profile +used.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Check the local package for errors: + + cargo check + +2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md) diff --git a/src/doc/src/commands/cargo-clean.md b/src/doc/src/commands/cargo-clean.md index df321febee8..6e0ac29f714 100644 --- a/src/doc/src/commands/cargo-clean.md +++ b/src/doc/src/commands/cargo-clean.md @@ -1,3 +1,182 @@ -# cargo clean -{{#include command-common.html}} -{{#include ../../man/generated/cargo-clean.html}} +# cargo-clean(1) + + +## NAME + +cargo-clean - Remove generated artifacts + +## SYNOPSIS + +`cargo clean` [_options_] + +## 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 + +### 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 cargo-pkgid(1) for the SPEC format.
+ +
+ +### Clean Options + +
+ +
--doc
+
This option will cause cargo clean to remove only the doc directory in +the target directory.
+ + +
--release
+
Clean all artifacts that were built with the release or bench profiles.
+ + +
--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. Defaults +to target in the root of the workspace.
+ + + +
--target triple
+
Clean 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Remove the entire target directory: + + cargo clean + +2. Remove only the release artifacts: + + cargo clean --release + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md) diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index 9cdd897048d..02caad726a8 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -1,3 +1,333 @@ -# cargo doc -{{#include command-common.html}} -{{#include ../../man/generated/cargo-doc.html}} +# cargo-doc(1) + + +## NAME + +cargo-doc - Build a package's documentation + +## SYNOPSIS + +`cargo doc` [_options_] + +## DESCRIPTION + +Build the documentation for the local package and all dependencies. The output +is placed in `target/doc` in rustdoc's usual format. + +## 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.
+ + +
--no-deps
+
Do not build documentation for dependencies.
+ + +
--document-private-items
+
Include non-public items in the documentation.
+ + +
+ +### 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 +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +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...
+
Document only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Document all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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 +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +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. + +
+
--lib
+
Document the package's library.
+ + +
--bin name...
+
Document the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Document all binary targets.
+ + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Document 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Document optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build the local package documentation and its dependencies and output to + `target/doc`. + + cargo doc + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-rustdoc(1)](cargo-rustdoc.md), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/doc/src/commands/cargo-fetch.md b/src/doc/src/commands/cargo-fetch.md index bb5beda1e78..fa5158d8103 100644 --- a/src/doc/src/commands/cargo-fetch.md +++ b/src/doc/src/commands/cargo-fetch.md @@ -1,3 +1,155 @@ -# cargo fetch -{{#include command-common.html}} -{{#include ../../man/generated/cargo-fetch.html}} +# cargo-fetch(1) + + +## NAME + +cargo-fetch - Fetch dependencies of a package from the network + +## SYNOPSIS + +`cargo fetch` [_options_] + +## 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 +available. Subsequent Cargo commands never touch the network after a `cargo +fetch` unless the lock file changes. + +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. + +If `--target` is not specified, then all target dependencies are fetched. + +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 + +### Fetch options + +
+
--target triple
+
Fetch 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Fetch all dependencies: + + cargo fetch + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-update(1)](cargo-update.md), [cargo-generate-lockfile(1)](cargo-generate-lockfile.md) diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index 66503337a23..b811ab9eaa0 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -1,3 +1,436 @@ -# cargo fix -{{#include command-common.html}} -{{#include ../../man/generated/cargo-fix.html}} +# cargo-fix(1) + + +## NAME + +cargo-fix - Automatically fix lint warnings reported by rustc + +## SYNOPSIS + +`cargo fix` [_options_] + +## DESCRIPTION + +This Cargo subcommand will automatically take rustc's suggestions from +diagnostics like warnings and apply them to your source code. This is intended +to help automate tasks that rustc itself already knows how to tell you to fix! +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 [cargo-check(1)](cargo-check.md). 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 +executing: + + cargo fix --edition + +which behaves the same as `cargo check --all-targets`. + +`cargo fix` is only capable of fixing code that is normally compiled with +`cargo check`. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed: + + cargo fix --edition --features foo + +Similarly, other `cfg` expressions like platform-specific code will need to +pass `--target` to fix code for the given target. + + cargo fix --edition --target x86_64-pc-windows-gnu + +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 + + +## 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.
+ + +
--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.
+ + +
--edition-idioms
+
Apply suggestions that will update code to the preferred style for the current +edition.
+ + +
--allow-no-vcs
+
Fix code even if a VCS was not detected.
+ + +
--allow-dirty
+
Fix code even if the working directory has changes.
+ + +
--allow-staged
+
Fix code even if the working directory has staged changes.
+ + +
+ +### 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 +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +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...
+
Fix only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Fix all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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. + +Passing target selection flags will fix only the specified +targets. + +
+ +
--lib
+
Fix the package's library.
+ + +
--bin name...
+
Fix the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Fix all binary targets.
+ + + +
--example name...
+
Fix the specified example. This flag may be specified multiple times.
+ + +
--examples
+
Fix all example targets.
+ + +
--test name...
+
Fix the specified integration test. This flag may be specified +multiple times.
+ + +
--tests
+
Fix 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.
+ + +
--bench name...
+
Fix the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Fix 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.
+ + +
--all-targets
+
Fix all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Fix 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Fix optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
--profile name
+
Changes fix behavior. Currently only test is supported, +which will fix with the #[cfg(test)] attribute enabled. +This is useful to have it fix unit tests which are usually +excluded via the cfg attribute. This does not change the actual profile +used.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Apply compiler suggestions to the local package: + + cargo fix + +2. Convert a 2015 edition to 2018: + + cargo fix --edition + +3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-check(1)](cargo-check.md) diff --git a/src/doc/src/commands/cargo-generate-lockfile.md b/src/doc/src/commands/cargo-generate-lockfile.md index 57b70691138..79b1decc04e 100644 --- a/src/doc/src/commands/cargo-generate-lockfile.md +++ b/src/doc/src/commands/cargo-generate-lockfile.md @@ -1,3 +1,130 @@ -# cargo generate-lockfile -{{#include command-common.html}} -{{#include ../../man/generated/cargo-generate-lockfile.html}} +# cargo-generate-lockfile(1) + +## NAME + +cargo-generate-lockfile - Generate the lockfile for a package + +## SYNOPSIS + +`cargo generate-lockfile` [_options_] + +## 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 [cargo-update(1)](cargo-update.md) which is also capable of creating a `Cargo.lock` +lockfile and has more options for controlling update behavior. + +## OPTIONS + +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-update(1)](cargo-update.md) diff --git a/src/doc/src/commands/cargo-help.md b/src/doc/src/commands/cargo-help.md index 7e1ba07307e..a5acfd284aa 100644 --- a/src/doc/src/commands/cargo-help.md +++ b/src/doc/src/commands/cargo-help.md @@ -1,3 +1,26 @@ -# cargo help -{{#include command-common.html}} -{{#include ../../man/generated/cargo-help.html}} +# cargo-help(1) + +## NAME + +cargo-help - Get help for a Cargo command + +## SYNOPSIS + +`cargo help` [_subcommand_] + +## DESCRIPTION + +Prints a help message for the given command. + +## EXAMPLES + +1. Get help for a command: + + cargo help build + +2. Help is also available with the `--help` flag: + + cargo build --help + +## SEE ALSO +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-init.md b/src/doc/src/commands/cargo-init.md index 044a8b12dca..b0389287c8f 100644 --- a/src/doc/src/commands/cargo-init.md +++ b/src/doc/src/commands/cargo-init.md @@ -1,3 +1,169 @@ -# cargo init -{{#include command-common.html}} -{{#include ../../man/generated/cargo-init.html}} +# cargo-init(1) + +## NAME + +cargo-init - Create a new Cargo package in an existing directory + +## SYNOPSIS + +`cargo init` [_options_] [_path_] + +## 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. + +If there are typically-named Rust source files already in the directory, those +will be used. If not, then a sample `src/main.rs` file will be created, or +`src/lib.rs` if `--lib` is passed. + +If the directory is not already in a VCS repository, then a new repository +is created (see `--vcs` below). + +The "authors" field in the manifest is determined from the environment or +configuration settings. A name is required and is determined from (first match +wins): + +- `cargo-new.name` Cargo config value +- `CARGO_NAME` environment variable +- `GIT_AUTHOR_NAME` environment variable +- `GIT_COMMITTER_NAME` environment variable +- `user.name` git configuration value +- `USER` environment variable +- `USERNAME` environment variable +- `NAME` environment variable + +The email address is optional and is determined from: + +- `cargo-new.email` Cargo config value +- `CARGO_EMAIL` environment variable +- `GIT_AUTHOR_EMAIL` environment variable +- `GIT_COMMITTER_EMAIL` environment variable +- `user.email` git configuration value +- `EMAIL` environment variable + +See [the reference](../reference/config.html) for more information about +configuration files. + + +See [cargo-new(1)](cargo-new.md) for a similar command which will create a new package in +a new directory. + +## OPTIONS + +### Init Options + +
+ +
--bin
+
Create a package with a binary target (src/main.rs). +This is the default behavior.
+ + +
--lib
+
Create a package with a library target (src/lib.rs).
+ + +
--edition edition
+
Specify the Rust edition to use. Default is 2018. +Possible values: 2015, 2018
+ + +
--name name
+
Set the package name. Defaults to the directory name.
+ + +
--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.
+ + +
--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. +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.

+ + +
+ + +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create a binary Cargo package in the current directory: + + cargo init + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-new(1)](cargo-new.md) diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 5fa11a60d57..bb11620fb8a 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -1,3 +1,354 @@ -# cargo install -{{#include command-common.html}} -{{#include ../../man/generated/cargo-install.html}} +# cargo-install(1) + + +## NAME + +cargo-install - Build and install a Rust binary + +## SYNOPSIS + +`cargo install` [_options_] _crate_...\ +`cargo install` [_options_] `--path` _path_\ +`cargo install` [_options_] `--git` _url_ [_crate_...]\ +`cargo install` [_options_] `--list` + +## DESCRIPTION + +This command manages Cargo's local set of installed binary crates. Only +packages which have executable `[[bin]]` or `[[example]]` targets can be +installed, and all executables are installed into the installation root's +`bin` folder. + +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo [config value](../reference/config.html) +- `CARGO_HOME` environment variable +- `$HOME/.cargo` + + +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 +required to indicate which crate should be installed. + +Crates from crates.io can optionally specify the version they wish to install +via the `--version` flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the `--bin` argument can selectively install only +one of them, and if you'd rather install examples the `--example` argument can +be used as well. + +If the package is already installed, Cargo will reinstall it if the installed +version does not appear to be up-to-date. If any of the following values +change, then Cargo will reinstall the package: + +- The package version and source. +- The set of binary names installed. +- The chosen features. +- The release mode (`--debug`). +- The target (`--target`). + +Installing with `--path` will always build and install, unless there are +conflicting binaries from another package. The `--force` flag may be used to +force Cargo to always reinstall the package. + +If the source is crates.io or `--git` then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the `CARGO_TARGET_DIR` environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems. + +By default, the `Cargo.lock` file that is included with the package will be +ignored. This means that Cargo will recompute which versions of dependencies +to use, possibly using newer versions that have been released since the +package was published. The `--locked` flag can be used to force Cargo to use +the packaged `Cargo.lock` file if it is available. This may be useful for +ensuring reproducible builds, to use the exact same set of dependencies that +were available when the package was published. It may also be useful if a +newer version of a dependency is published that no longer builds on your +system, or has other problems. The downside to using `--locked` is that you +will not receive any fixes or updates to any dependency. Note that Cargo did +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 + +### Install Options + +
+ +
--vers version
+
--version version
+
Specify a version to install. This may be a 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.
+ + +
--git url
+
Git URL to install the specified crate from.
+ + +
--branch branch
+
Branch to use when installing from git.
+ + +
--tag tag
+
Tag to use when installing from git.
+ + +
--rev sha
+
Specific commit to use when installing from git.
+ + +
--path path
+
Filesystem path to local crate to install.
+ + +
--list
+
List all installed packages and their versions.
+ + +
-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.
+ + +
--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.
+ + +
--bin name...
+
Install only the specified binary.
+ + +
--bins
+
Install all binaries.
+ + +
--example name...
+
Install only the specified example.
+ + +
--examples
+
Install all examples.
+ + +
--root dir
+
Directory to install packages into.
+ + +
--registry registry
+
Name of the registry to use. Registry names are defined in 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.
+ + + +
--index index
+
The URL of the registry index to use.
+ + + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Install 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--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. Defaults +to target in the root of the workspace.
+ + + +
--debug
+
Build with the dev profile instead the release profile.
+ + +
+ +### Manifest Options + +
+
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Install or upgrade a package from crates.io: + + cargo install ripgrep + +2. Install or reinstall the package in the current directory: + + cargo install --path . + +3. View the list of installed packages: + + cargo install --list + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-uninstall(1)](cargo-uninstall.md), [cargo-search(1)](cargo-search.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-locate-project.md b/src/doc/src/commands/cargo-locate-project.md index 0e42adfe404..dff40101277 100644 --- a/src/doc/src/commands/cargo-locate-project.md +++ b/src/doc/src/commands/cargo-locate-project.md @@ -1,3 +1,104 @@ -# cargo locate-project -{{#include command-common.html}} -{{#include ../../man/generated/cargo-locate-project.html}} +# cargo-locate-project(1) + +## NAME + +cargo-locate-project - Print a JSON representation of a Cargo.toml file's location + +## SYNOPSIS + +`cargo locate-project` [_options_] + +## DESCRIPTION + +This command will print a JSON object to stdout with the full path to the +`Cargo.toml` manifest. + +See also [cargo-metadata(1)](cargo-metadata.md) which is capable of returning the path to a +workspace root. + +## OPTIONS + +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Manifest Options + +
+
--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.
+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Display the path to the manifest based on the current directory: + + cargo locate-project + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-metadata(1)](cargo-metadata.md) diff --git a/src/doc/src/commands/cargo-login.md b/src/doc/src/commands/cargo-login.md index 5feddeead3e..601e49f246b 100644 --- a/src/doc/src/commands/cargo-login.md +++ b/src/doc/src/commands/cargo-login.md @@ -1,3 +1,111 @@ -# cargo login -{{#include command-common.html}} -{{#include ../../man/generated/cargo-login.html}} +# cargo-login(1) + +## NAME + +cargo-login - Save an API token from the registry locally + +## SYNOPSIS + +`cargo login` [_options_] [_token_] + +## DESCRIPTION + +This command will save the API token to disk so that commands that require +authentication, such as [cargo-publish(1)](cargo-publish.md), 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. + +The API token for crates.io may be retrieved from . + +Take care to keep the token secret, it should not be shared with anyone else. + +## OPTIONS + +### Login Options + +
+
--registry registry
+
Name of the registry to use. Registry names are defined in 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.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Save the API token to disk: + + cargo login + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md index 273221395e7..0e0edcdc405 100644 --- a/src/doc/src/commands/cargo-metadata.md +++ b/src/doc/src/commands/cargo-metadata.md @@ -1,3 +1,448 @@ -# cargo metadata -{{#include command-common.html}} -{{#include ../../man/generated/cargo-metadata.html}} +# cargo-metadata(1) +:source-highlighter: highlightjs + +## NAME + +cargo-metadata - Machine-readable metadata about the current package + +## SYNOPSIS + +`cargo metadata` [_options_] + +## DESCRIPTION + +Output JSON to stdout containing information about the workspace members and +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 [cargo_metadata crate](https://crates.io/crates/cargo_metadata) +for a Rust API for reading the metadata. + +## OUTPUT FORMAT + +The output has the following format: + +```javascript +{ + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* A string of the URL of the registry this dependency is from. + If not specified or null, the dependency is from the default + registry (crates.io). + */ + "registry": null + } + ], + /* Array of Cargo targets. */ + "targets": [ + { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "bin" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "bin" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/main.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": false, + /* Whether or not this target should be built and run with `--test` + */ + "test": true + } + ], + /* Set of features defined for the package. + Each feature maps to an array of features or dependencies it + enables. + */ + "features": { + "default": [ + "feat1" + ], + "feat1": [], + "feat2": [] + }, + /* Absolute path to this package's manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* Package metadata. + This is null if no metadata is specified. + */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + }, + /* List of registries to which this package may be published. + Publishing is unrestricted if null, and forbidden if an empty array. */ + "publish": [ + "crates-io" + ], + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe " + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018", + /* Optional string that is the name of a native library the package + is linking to. + */ + "links": null, + } + ], + /* Array of members of the workspace. + Each entry is the Package ID for the package. + */ + "workspace_members": [ + "my-package 0.1.0 (path+file:///path/to/my-package)", + ], + // The resolved dependency graph for the entire workspace. The enabled + // features are based on the enabled features for the "current" package. + // Inactivated optional dependencies are not listed. + // + // This is null if --no-deps is specified. + // + // By default, this includes all dependencies for all target platforms. + // The `--filter-platform` flag may be used to narrow to a specific + // target triple. + "resolve": { + /* Array of nodes within the dependency graph. + Each node is a package. + */ + "nodes": [ + { + /* The Package ID of this node. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The dependencies of this package, an array of Package IDs. */ + "dependencies": [ + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" + ], + /* The dependencies of this package. This is an alternative to + "dependencies" which contains additional information. In + particular, this handles renamed dependencies. + */ + "deps": [ + { + /* The name of the dependency's library target. + If this is a renamed dependency, this is the new + name. + */ + "name": "bitflags", + /* The Package ID of the dependency. */ + "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + /* Array of dependency kinds. Added in Cargo 1.40. */ + "dep_kinds": [ + { + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)" + } + ] + } + ], + /* Array of features enabled on this package. */ + "features": [ + "default" + ] + } + ], + /* The root package of the workspace. + This is null if this is a virtual workspace. Otherwise it is + the Package ID of the root package. + */ + "root": "my-package 0.1.0 (path+file:///path/to/my-package)" + }, + /* The absolute path to the build directory where Cargo places its output. */ + "target_directory": "/path/to/my-package/target", + /* The version of the schema for this metadata structure. + This will be changed if incompatible changes are ever made. + */ + "version": 1, + /* The absolute path to the root of the workspace. */ + "workspace_root": "/path/to/my-package" + /* Workspace metadata. + This is null if no metadata is specified. */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + } +} +```` + +## OPTIONS + +### Output Options + +
+ +
--no-deps
+
Output information only about the workspace members and don't fetch +dependencies.
+ + +
--format-version version
+
Specify the version of the output format to use. Currently 1 is the only +possible value.
+ + +
--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.

+ + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Output JSON about the current package: + + cargo metadata --format-version=1 + +## SEE ALSO +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-new.md b/src/doc/src/commands/cargo-new.md index 3f1a490244d..27d4ca316e8 100644 --- a/src/doc/src/commands/cargo-new.md +++ b/src/doc/src/commands/cargo-new.md @@ -1,3 +1,164 @@ -# cargo new -{{#include command-common.html}} -{{#include ../../man/generated/cargo-new.html}} +# cargo-new(1) + +## NAME + +cargo-new - Create a new Cargo package + +## SYNOPSIS + +`cargo new` [_options_] _path_ + +## 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). + +The "authors" field in the manifest is determined from the environment or +configuration settings. A name is required and is determined from (first match +wins): + +- `cargo-new.name` Cargo config value +- `CARGO_NAME` environment variable +- `GIT_AUTHOR_NAME` environment variable +- `GIT_COMMITTER_NAME` environment variable +- `user.name` git configuration value +- `USER` environment variable +- `USERNAME` environment variable +- `NAME` environment variable + +The email address is optional and is determined from: + +- `cargo-new.email` Cargo config value +- `CARGO_EMAIL` environment variable +- `GIT_AUTHOR_EMAIL` environment variable +- `GIT_COMMITTER_EMAIL` environment variable +- `user.email` git configuration value +- `EMAIL` environment variable + +See [the reference](../reference/config.html) for more information about +configuration files. + + +See [cargo-init(1)](cargo-init.md) for a similar command which will create a new manifest +in an existing directory. + +## OPTIONS + +### New Options + +
+ +
--bin
+
Create a package with a binary target (src/main.rs). +This is the default behavior.
+ + +
--lib
+
Create a package with a library target (src/lib.rs).
+ + +
--edition edition
+
Specify the Rust edition to use. Default is 2018. +Possible values: 2015, 2018
+ + +
--name name
+
Set the package name. Defaults to the directory name.
+ + +
--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.
+ + +
--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. +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.

+ + +
+ + +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create a binary Cargo package in the given directory: + + cargo new foo + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-init(1)](cargo-init.md) diff --git a/src/doc/src/commands/cargo-owner.md b/src/doc/src/commands/cargo-owner.md index c1dbc9eb6c7..a5aaee9ef69 100644 --- a/src/doc/src/commands/cargo-owner.md +++ b/src/doc/src/commands/cargo-owner.md @@ -1,3 +1,157 @@ -# cargo owner -{{#include command-common.html}} -{{#include ../../man/generated/cargo-owner.html}} +# cargo-owner(1) + +## NAME + +cargo-owner - Manage the owners of a crate on the registry + +## SYNOPSIS + +`cargo owner` [_options_] `--add` _login_ [_crate_]\ +`cargo owner` [_options_] `--remove` _login_ [_crate_]\ +`cargo owner` [_options_] `--list` [_crate_] + +## 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 [cargo-login(1)](cargo-login.md). + +If the crate name is not specified, it will use the package name from the +current directory. + +See [the reference](../reference/publishing.html#cargo-owner) for more +information about owners and publishing. + +## OPTIONS + +### Owner Options + +
+ +
-a
+
--add login...
+
Invite the given user or team as an owner.
+ + +
-r
+
--remove login...
+
Remove the given user or team as an owner.
+ + +
-l
+
--list
+
List owners of a crate.
+ + +
--token token
+
API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by cargo-login(1)).

+

Cargo config 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.

+ + + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in 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.
+ + + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. List owners of a package: + + cargo owner --list foo + +2. Invite an owner to a package: + + cargo owner --add username foo + +3. Remove an owner from a package: + + cargo owner --remove username foo + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-login(1)](cargo-login.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md index 8bfedcfa40d..0cab5b3feac 100644 --- a/src/doc/src/commands/cargo-package.md +++ b/src/doc/src/commands/cargo-package.md @@ -1,3 +1,251 @@ -# cargo package -{{#include command-common.html}} -{{#include ../../man/generated/cargo-package.html}} +# cargo-package(1) + + +## NAME + +cargo-package - Assemble the local package into a distributable tarball + +## SYNOPSIS + +`cargo package` [_options_] + +## 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: + +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. +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. [cargo-install(1)](cargo-install.md) 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`). +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. +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 [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +## OPTIONS + +### Package Options + +
+ +
-l
+
--list
+
Print files included in a package without making one.
+ + +
--no-verify
+
Don't verify the contents by building them.
+ + +
--no-metadata
+
Ignore warnings about a lack of human-usable metadata (such as the description +or the license).
+ + +
--allow-dirty
+
Allow working directories with uncommitted VCS changes to be packaged.
+ + +
+ +### Compilation Options + +
+ +
--target triple
+
Package 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--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. Defaults +to target in the root of the workspace.
+ + + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Create a compressed `.crate` file of the current package: + + cargo package + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md index 7481ad1c7af..866888acaac 100644 --- a/src/doc/src/commands/cargo-pkgid.md +++ b/src/doc/src/commands/cargo-pkgid.md @@ -1,3 +1,167 @@ -# cargo pkgid -{{#include command-common.html}} -{{#include ../../man/generated/cargo-pkgid.html}} +# cargo-pkgid(1) + +## NAME + +cargo-pkgid - Print a fully qualified package specification + +## SYNOPSIS + +`cargo pkgid` [_options_] [_spec_] + +## DESCRIPTION + +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 +package is printed. + +This command requires that a lockfile is available and dependencies have been +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 +following: + +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` + +## OPTIONS + +### Package Selection + +
+ +
-p spec
+
--package spec
+
Get the package ID for the given package instead of the current package.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Retrieve package specification for `foo` package: + + cargo pkgid foo + +2. Retrieve package specification for version 1.0.0 of `foo`: + + cargo pkgid foo:1.0.0 + +3. Retrieve package specification for `foo` from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-generate-lockfile(1)](cargo-generate-lockfile.md), [cargo-metadata(1)](cargo-metadata.md) diff --git a/src/doc/src/commands/cargo-publish.md b/src/doc/src/commands/cargo-publish.md index db45e789908..f881c32977e 100644 --- a/src/doc/src/commands/cargo-publish.md +++ b/src/doc/src/commands/cargo-publish.md @@ -1,3 +1,257 @@ -# cargo publish -{{#include command-common.html}} -{{#include ../../man/generated/cargo-publish.html}} +# cargo-publish(1) + + +## NAME + +cargo-publish - Upload a package to the registry + +## SYNOPSIS + +`cargo publish` [_options_] + +## 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 . This performs the +following steps: + +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 [cargo-package(1)](cargo-package.md). +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 [cargo-login(1)](cargo-login.md). + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +## OPTIONS + +### Publish Options + +
+ +
--dry-run
+
Perform all checks without uploading.
+ + +
--token token
+
API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by cargo-login(1)).

+

Cargo config 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.

+ + + +
--no-verify
+
Don't verify the contents by building them.
+ + +
--allow-dirty
+
Allow working directories with uncommitted VCS changes to be packaged.
+ + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in 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.
+ + + +
+ +### Compilation Options + +
+ +
--target triple
+
Publish 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--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. Defaults +to target in the root of the workspace.
+ + + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Publish the current package: + + cargo publish + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-package(1)](cargo-package.md), [cargo-login(1)](cargo-login.md) diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 16d92815f09..40c56b7ee84 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -1,3 +1,294 @@ -# cargo run -{{#include command-common.html}} -{{#include ../../man/generated/cargo-run.html}} +# cargo-run(1) + + +## NAME + +cargo-run - Run the current package + +## SYNOPSIS + +`cargo run` [_options_] [`--` _args_] + +## DESCRIPTION + +Run a binary or example of the local package. + +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 + +### 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 run. See cargo-pkgid(1) for the SPEC +format.
+ + +
+ + +### 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.
+ + +
--example name
+
Run the specified example.
+ + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Run 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Run optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + + +
+ +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## 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 +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md) diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index ad6b3d98774..c0d4bf24fc9 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -1,3 +1,356 @@ -# cargo rustc -{{#include command-common.html}} -{{#include ../../man/generated/cargo-rustc.html}} +# cargo-rustc(1) + + +## NAME + +cargo-rustc - Compile the current package, and pass extra options to the compiler + +## SYNOPSIS + +`cargo rustc` [_options_] [`--` _args_] + +## 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 +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. + +See for documentation on rustc +flags. + +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of `--lib`, `--bin`, etc, must be used to select which +target is compiled. + +To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` +[environment variable](../reference/environment-variables.html) or the +`build.rustflags` [config value](../reference/config.html). + +## OPTIONS + +### 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 build. See cargo-pkgid(1) for the SPEC +format.
+ + +
+ + +### Target Selection + +When no target selection options are given, `cargo rustc` will build all +binary and library targets of the selected package. + +Passing target selection flags will build only the specified +targets. + +
+ +
--lib
+
Build the package's library.
+ + +
--bin name...
+
Build the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Build all binary targets.
+ + + +
--example name...
+
Build the specified example. This flag may be specified multiple times.
+ + +
--examples
+
Build all example targets.
+ + +
--test name...
+
Build the specified integration test. This flag may be specified +multiple times.
+ + +
--tests
+
Build 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.
+ + +
--bench name...
+
Build the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Build 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.
+ + +
--all-targets
+
Build all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Build 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Build optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + + +
+ +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## 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 +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md), [rustc(1)](https://doc.rust-lang.org/rustc/index.html) diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index a8ebf1950ea..8659e08eced 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -1,3 +1,360 @@ -# cargo rustdoc -{{#include command-common.html}} -{{#include ../../man/generated/cargo-rustdoc.html}} +# cargo-rustdoc(1) + + +## NAME + +cargo-rustdoc - Build a package's documentation, using specified custom flags + +## SYNOPSIS + +`cargo rustdoc` [_options_] [`--` _args_] + +## 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 +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 +be added to the rustdoc invocation. + +See for documentation on rustdoc +flags. + +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of `--lib`, `--bin`, etc, must be used to select which +target is compiled. + +To pass flags to all rustdoc processes spawned by Cargo, use the +`RUSTDOCFLAGS` [environment variable](../reference/environment-variables.html) +or the `build.rustdocflags` [config value](../reference/config.html). + +## 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.
+ + +
+ +### 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 document. See cargo-pkgid(1) for the SPEC +format.
+ + +
+ + +### 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. + +Passing target selection flags will document only the specified +targets. + +
+ +
--lib
+
Document the package's library.
+ + +
--bin name...
+
Document the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Document all binary targets.
+ + + +
--example name...
+
Document the specified example. This flag may be specified multiple times.
+ + +
--examples
+
Document all example targets.
+ + +
--test name...
+
Document the specified integration test. This flag may be specified +multiple times.
+ + +
--tests
+
Document 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.
+ + +
--bench name...
+
Document the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Document 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.
+ + +
--all-targets
+
Document all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Document 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Document optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + +
+ +### Manifest Options + +
+
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### Miscellaneous Options + +
+
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-doc(1)](cargo-doc.md), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/doc/src/commands/cargo-search.md b/src/doc/src/commands/cargo-search.md index b872d9628fb..ed5de00e34d 100644 --- a/src/doc/src/commands/cargo-search.md +++ b/src/doc/src/commands/cargo-search.md @@ -1,3 +1,115 @@ -# cargo search -{{#include command-common.html}} -{{#include ../../man/generated/cargo-search.html}} +# cargo-search(1) + +## NAME + +cargo-search - Search packages in crates.io + +## SYNOPSIS + +`cargo search` [_options_] [_query_...] + +## DESCRIPTION + +This performs a textual search for crates on . The matching +crates will be displayed along with their description in TOML format suitable +for copying into a `Cargo.toml` manifest. + +## OPTIONS + +### Search Options + +
+ +
--limit limit
+
Limit the number of results (default: 10, max: 100).
+ + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in 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.
+ + + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Search for a package from crates.io: + + cargo search serde + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-install(1)](cargo-install.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 52fc969128d..31f18e559c2 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -1,3 +1,468 @@ -# cargo test -{{#include command-common.html}} -{{#include ../../man/generated/cargo-test.html}} +# cargo-test(1) + + + +## NAME + +cargo-test - Execute unit and integration tests of a package + +## SYNOPSIS + +`cargo test` [_options_] [_testname_] [`--` _test-options_] + +## DESCRIPTION + +Compile and execute unit and integration tests. + +The test filtering argument `TESTNAME` and all the arguments following the two +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`. + +As an example, this will filter for tests with `foo` in their name and run them +on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + +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 functions will also be run with one iteration to verify that they +are functional. + +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 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 +[rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information on +writing doc tests. + +## OPTIONS + +### Test Options + +
+ +
--no-run
+
Compile, but don't run tests.
+ + +
--no-fail-fast
+
Run all tests regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all tests +within the executable to completion, this flag only applies to the executable +as a whole.
+ + +
+ + +### 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 +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +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...
+
Test only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Test all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### Target Selection + +When no target selection options are given, `cargo test` will build the +following targets of the selected packages: + +- lib — used to link with binaries, examples, integration tests, and doc tests +- bins (only if integration tests are built and required features are + available) +- examples — to ensure they compile +- lib as a unit test +- bins as unit tests +- integration tests +- doc tests for the lib target + +The default behavior can be changed by setting the `test` flag for the target +in the manifest settings. Setting examples to `test = true` will build and run +the example as a test. Setting targets to `test = false` will stop them from +being tested by default. Target selection options that take a target by name +ignore the `test` flag and will always test the given target. + +Doc tests for libraries may be disabled by setting `doctest = false` for the +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_` +[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 +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + +Passing target selection flags will test only the specified +targets. + +
+ +
--lib
+
Test the package's library.
+ + +
--bin name...
+
Test the specified binary. This flag may be specified multiple times.
+ + +
--bins
+
Test all binary targets.
+ + + +
--example name...
+
Test the specified example. This flag may be specified multiple times.
+ + +
--examples
+
Test all example targets.
+ + +
--test name...
+
Test the specified integration test. This flag may be specified +multiple times.
+ + +
--tests
+
Test 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.
+ + +
--bench name...
+
Test the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Test 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.
+ + +
--all-targets
+
Test all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +
+ +
--doc
+
Test only the library's documentation. This cannot be mixed with other +target options.
+ + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Compilation Options + +
+ +
--target triple
+
Test 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 +config value.

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Test optimized artifacts with the release profile. See the +PROFILES section for details on how this affects profile +selection.
+ + + +
+ +### Output Options + +
+
--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. Defaults +to target in the root of the workspace.
+ + +
+ +### 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 +`--nocapture` to the test binaries: + + cargo test -- --nocapture + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
--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 +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +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.
    • +
+ + + +
+ +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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 +includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + +
+ +
-j N
+
--jobs N
+
Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.
+ + + +
+ +## PROFILES + +Profiles may be used to configure compiler options such as optimization levels +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. + +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. + + +Unit tests are separate executable artifacts which use the `test`/`bench` +profiles. Example targets are built the same as with `cargo build` (using the +`dev`/`release` profiles) unless you are building them with the test harness +(by setting `test = true` in the manifest or using the `--example` flag) in +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. + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Execute all the unit and integration tests of the current package: + + cargo test + +2. Run only tests whose names match against a filter string: + + cargo test name_filter + +3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-bench(1)](cargo-bench.md) diff --git a/src/doc/src/commands/cargo-tree.md b/src/doc/src/commands/cargo-tree.md index 0b134a71569..96adb5ccd8b 100644 --- a/src/doc/src/commands/cargo-tree.md +++ b/src/doc/src/commands/cargo-tree.md @@ -1,3 +1,384 @@ -# cargo tree -{{#include command-common.html}} -{{#include ../../man/generated/cargo-tree.html}} +# cargo-tree(1) + + + +## NAME + +cargo-tree - Display a tree visualization of a dependency graph + +## SYNOPSIS + +`cargo tree` [_options_] + +## 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 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── 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 +repeated. Use the `--no-dedupe` option to repeat the duplicates. + +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 + +### Tree Options + +
+ +
-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.

+ + +
--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.
+ + +
-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.

+ + +
-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.

+ + +
--target triple
+
Filter dependencies matching the given target-triple. The default is the host +platform. Use the value all to include all targets.
+ + +
+ +### Tree Formatting Options + +
+ +
--charset charset
+
Chooses the character set to use for the tree. Valid values are "utf8" or +"ascii". Default is "utf8".
+ + +
-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.
    • +
  • {f} — Comma-separated list of package features that are enabled.
    • +
+ + +
--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.
    • +
+ + +
+ +### 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 +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +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...
+
Display only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Display all members in the workspace.
+ + + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### 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 +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +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.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Display the tree for the package in the current directory: + + cargo tree + +2. Display all the packages that depend on the `syn` package: + + cargo tree -i syn + +3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + +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 +[cargo(1)](cargo.md), [cargo-metadata(1)](cargo-metadata.md) diff --git a/src/doc/src/commands/cargo-uninstall.md b/src/doc/src/commands/cargo-uninstall.md index 971ad3435df..36186f03ef8 100644 --- a/src/doc/src/commands/cargo-uninstall.md +++ b/src/doc/src/commands/cargo-uninstall.md @@ -1,3 +1,125 @@ -# cargo uninstall -{{#include command-common.html}} -{{#include ../../man/generated/cargo-uninstall.html}} +# cargo-uninstall(1) + +## NAME + +cargo-uninstall - Remove a Rust binary + +## SYNOPSIS + +`cargo uninstall` [_options_] [_spec_...] + +## DESCRIPTION + +This command removes a package installed with [cargo-install(1)](cargo-install.md). The _spec_ +argument is a package ID specification of the package to remove (see +[cargo-pkgid(1)](cargo-pkgid.md)). + +By default all binaries are removed for a crate but the `--bin` and +`--example` flags can be used to only remove particular binaries. + +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo [config value](../reference/config.html) +- `CARGO_HOME` environment variable +- `$HOME/.cargo` + + +## OPTIONS + +### Install Options + +
+ +
-p
+
--package spec...
+
Package to uninstall.
+ + +
--bin name...
+
Only uninstall the binary name.
+ + +
--root dir
+
Directory to uninstall packages from.
+ + +
+ +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-install(1)](cargo-install.md) diff --git a/src/doc/src/commands/cargo-update.md b/src/doc/src/commands/cargo-update.md index 2be849863f3..c07bf49c73b 100644 --- a/src/doc/src/commands/cargo-update.md +++ b/src/doc/src/commands/cargo-update.md @@ -1,3 +1,170 @@ -# cargo update -{{#include command-common.html}} -{{#include ../../man/generated/cargo-update.html}} +# cargo-update(1) + +## NAME + +cargo-update - Update dependencies as recorded in the local lock file + +## SYNOPSIS + +`cargo update` [_options_] + +## 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 [cargo-build(1)](cargo-build.md) or [cargo-generate-lockfile(1)](cargo-generate-lockfile.md). + +## OPTIONS + +### Update Options + +
+ +
-p spec...
+
--package spec...
+
Update only the specified packages. This flag may be specified +multiple times. See 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.

+ + +
--aggressive
+
When used with -p, dependencies of spec are forced to update as well. +Cannot be used with --precise.
+ + +
--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).
+ + +
--dry-run
+
Displays what would be updated, but doesn't actually write the lockfile.
+ + +
+ +### Display Options + +
+
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + +
+ +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Update all dependencies in the lockfile: + + cargo update + +2. Update only specific dependencies: + + cargo update -p foo -p bar + +3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-generate-lockfile(1)](cargo-generate-lockfile.md) diff --git a/src/doc/src/commands/cargo-vendor.md b/src/doc/src/commands/cargo-vendor.md index 1e0f333fe6d..e40e6991579 100644 --- a/src/doc/src/commands/cargo-vendor.md +++ b/src/doc/src/commands/cargo-vendor.md @@ -1,4 +1,175 @@ -# cargo vendor -{{#include command-common.html}} -{{#include ../../man/generated/cargo-vendor.html}} +# cargo-vendor(1) + +## NAME + +cargo-vendor - Vendor all dependencies locally + +## SYNOPSIS + +`cargo vendor` [_options_] [_path_] + +## DESCRIPTION + +This cargo subcommand will vendor all crates.io and git dependencies for a +project into the specified directory at ``. After this command completes +the vendor directory specified by `` will contain all remote sources from +dependencies specified. Additional manifests beyond the default one can be +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 + +### Vendor Options + +
+ +
-s manifest
+
--sync manifest
+
Specify extra Cargo.toml manifests to workspaces which should also be +vendored and synced to the output.
+ + +
--no-delete
+
Don't delete the "vendor" directory when vendoring, but rather keep all +existing contents of the vendor directory
+ + +
--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
+ + +
--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.
+ + +
+ +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Vendor all dependencies into a local "vendor" folder + + 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 +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-verify-project.md b/src/doc/src/commands/cargo-verify-project.md index 4a4c7668267..35a39787aa5 100644 --- a/src/doc/src/commands/cargo-verify-project.md +++ b/src/doc/src/commands/cargo-verify-project.md @@ -1,3 +1,135 @@ -# cargo verify-project -{{#include command-common.html}} -{{#include ../../man/generated/cargo-verify-project.html}} +# cargo-verify-project(1) + +## NAME + +cargo-verify-project - Check correctness of crate manifest + +## SYNOPSIS + +`cargo verify-project` [_options_] + +## 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: + + {"success":"true"} + +An invalid workspace will display: + + {"invalid":"human-readable error message"} + +## OPTIONS + +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
+ +### Manifest Options + +
+ +
--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.
+ + + +
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: The workspace is OK. +* `1`: The workspace is invalid. + +## EXAMPLES + +1. Check the current workspace for errors: + + cargo verify-project + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-package(1)](cargo-package.md) diff --git a/src/doc/src/commands/cargo-version.md b/src/doc/src/commands/cargo-version.md index 12833ede4d5..96a3455cd64 100644 --- a/src/doc/src/commands/cargo-version.md +++ b/src/doc/src/commands/cargo-version.md @@ -1,3 +1,42 @@ -# cargo version -{{#include command-common.html}} -{{#include ../../man/generated/cargo-version.html}} +# cargo-version(1) + +## NAME + +cargo-version - Show version information + +## SYNOPSIS + +`cargo version` [_options_] + +## DESCRIPTION + +Displays the version of Cargo. + +## OPTIONS + +
+ +
-v
+
--verbose
+
Display additional version information.
+ + +
+ +## EXAMPLES + +1. Display the version: + + cargo version + +2. The version is also available via flags: + + cargo --version + cargo -V + +3. Display extra version information: + + cargo -Vv + +## SEE ALSO +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-yank.md b/src/doc/src/commands/cargo-yank.md index d6ca7b3c6fd..fea02c57707 100644 --- a/src/doc/src/commands/cargo-yank.md +++ b/src/doc/src/commands/cargo-yank.md @@ -1,3 +1,143 @@ -# cargo yank -{{#include command-common.html}} -{{#include ../../man/generated/cargo-yank.html}} +# cargo-yank(1) + +## NAME + +cargo-yank - Remove a pushed crate from the index + +## SYNOPSIS + +`cargo yank` [_options_] `--vers` _version_ [_crate_] + +## 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 +still be available for download via the registry's download link. + +Note that existing crates locked to a yanked version will still be able to +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 [cargo-login(1)](cargo-login.md). + +If the crate name is not specified, it will use the package name from the +current directory. + +## OPTIONS + +### Yank Options + +
+ +
--vers version
+
The version to yank or un-yank.
+ + +
--undo
+
Undo a yank, putting a version back into the index.
+ + +
--token token
+
API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by cargo-login(1)).

+

Cargo config 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.

+ + + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in 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.
+ + + +
+ +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Yank a crate from the index: + + cargo yank --vers 1.0.7 foo + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-login(1)](cargo-login.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo.md b/src/doc/src/commands/cargo.md index a9ef0a2d231..007c87a18fe 100644 --- a/src/doc/src/commands/cargo.md +++ b/src/doc/src/commands/cargo.md @@ -1,3 +1,311 @@ -# cargo -{{#include command-common.html}} -{{#include ../../man/generated/cargo.html}} +# cargo(1) + +## NAME + +cargo - The Rust package manager + +## SYNOPSIS + +`cargo` [_options_] _command_ [_args_]\ +`cargo` [_options_] `--version`\ +`cargo` [_options_] `--list`\ +`cargo` [_options_] `--help`\ +`cargo` [_options_] `--explain` _code_ + +## DESCRIPTION + +This program is a package manager and build tool for the Rust language, +available at . + +## COMMANDS + +### Build Commands + +[cargo-bench(1)](cargo-bench.md)\ +    Execute benchmarks of a package. + +[cargo-build(1)](cargo-build.md)\ +    Compile a package. + +[cargo-check(1)](cargo-check.md)\ +    Check a local package and all of its dependencies for errors. + +[cargo-clean(1)](cargo-clean.md)\ +    Remove artifacts that Cargo has generated in the past. + +[cargo-doc(1)](cargo-doc.md)\ +    Build a package's documentation. + +[cargo-fetch(1)](cargo-fetch.md)\ +    Fetch dependencies of a package from the network. + +[cargo-fix(1)](cargo-fix.md)\ +    Automatically fix lint warnings reported by rustc. + +[cargo-run(1)](cargo-run.md)\ +    Run a binary or example of the local package. + +[cargo-rustc(1)](cargo-rustc.md)\ +    Compile a package, and pass extra options to the compiler. + +[cargo-rustdoc(1)](cargo-rustdoc.md)\ +    Build a package's documentation, using specified custom flags. + +[cargo-test(1)](cargo-test.md)\ +    Execute unit and integration tests of a package. + +### Manifest Commands + +[cargo-generate-lockfile(1)](cargo-generate-lockfile.md)\ +    Generate `Cargo.lock` for a project. + +[cargo-locate-project(1)](cargo-locate-project.md)\ +    Print a JSON representation of a `Cargo.toml` file's location. + +[cargo-metadata(1)](cargo-metadata.md)\ +    Output the resolved dependencies of a package in machine-readable format. + +[cargo-pkgid(1)](cargo-pkgid.md)\ +    Print a fully qualified package specification. + +[cargo-tree(1)](cargo-tree.md)\ +    Display a tree visualization of a dependency graph. + +[cargo-update(1)](cargo-update.md)\ +    Update dependencies as recorded in the local lock file. + +[cargo-vendor(1)](cargo-vendor.md)\ +    Vendor all dependencies locally. + +[cargo-verify-project(1)](cargo-verify-project.md)\ +    Check correctness of crate manifest. + +### Package Commands + +[cargo-init(1)](cargo-init.md)\ +    Create a new Cargo package in an existing directory. + +[cargo-install(1)](cargo-install.md)\ +    Build and install a Rust binary. + +[cargo-new(1)](cargo-new.md)\ +    Create a new Cargo package. + +[cargo-search(1)](cargo-search.md)\ +    Search packages in crates.io. + +[cargo-uninstall(1)](cargo-uninstall.md)\ +    Remove a Rust binary. + +### Publishing Commands + +[cargo-login(1)](cargo-login.md)\ +    Save an API token from the registry locally. + +[cargo-owner(1)](cargo-owner.md)\ +    Manage the owners of a crate on the registry. + +[cargo-package(1)](cargo-package.md)\ +    Assemble the local package into a distributable tarball. + +[cargo-publish(1)](cargo-publish.md)\ +    Upload a package to the registry. + +[cargo-yank(1)](cargo-yank.md)\ +    Remove a pushed crate from the index. + +### General Commands + +[cargo-help(1)](cargo-help.md)\ +    Display help information about Cargo. + +[cargo-version(1)](cargo-version.md)\ +    Show version information. + +## OPTIONS + +### Special Options + +
+ +
-V
+
--version
+
Print version info and exit. If used with --verbose, prints extra +information.
+ + +
--list
+
List all installed Cargo subcommands. If used with --verbose, prints extra +information.
+ + +
--explain code
+
Run rustc --explain CODE which will print out a detailed explanation of an +error message (for example, E0004).
+ + +
+ +### Display Options + +
+ +
-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.
+ + +
-q
+
--quiet
+
No output printed to stdout.
+ + +
--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 +config value.

+ + + +
+ +### Manifest Options + +
+
--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.

+ + +
--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 cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+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 +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## FILES + +`~/.cargo/`\ +    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/bin/`\ +    Binaries installed by [cargo-install(1)](cargo-install.md) will be located here. If using +rustup, executables distributed with Rust are also located here. + +`$CARGO_HOME/config.toml`\ +    The global configuration file. See [the reference](../reference/config.html) +for more information about configuration 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_HOME/credentials.toml`\ +    Private authentication information for logging in to a registry. + +`$CARGO_HOME/registry/`\ +    This directory contains cached downloads of the registry index and any +downloaded dependencies. + +`$CARGO_HOME/git/`\ +    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 + +1. Build a local package and all of its dependencies: + + cargo build + +2. Build a package with optimizations: + + cargo build --release + +3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + +4. Create a new package that builds an executable: + + cargo new foobar + +5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + +6. Learn about a command's options and usage: + + cargo help clean + +## BUGS + +See for issues. + +## SEE ALSO +[rustc(1)](https://doc.rust-lang.org/rustc/index.html), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index b17bb536dc9..e23d25268d6 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -1,488 +1,356 @@ '\" t -.\" Title: cargo-bench -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-BENCH" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-BENCH" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-bench \- Execute benchmarks of a package .SH "SYNOPSIS" -.sp -\fBcargo bench [\fIOPTIONS\fP] [BENCHNAME] [\-\- \fIBENCH\-OPTIONS\fP]\fP +\fBcargo bench\fR [\fIoptions\fR] [\fIbenchname\fR] [\fB\-\-\fR \fIbench\-options\fR] .SH "DESCRIPTION" -.sp Compile and execute benchmarks. .sp -The benchmark filtering argument \fBBENCHNAME\fP and all the arguments following -the two dashes (\fB\-\-\fP) are passed to the benchmark binaries and thus to -\fIlibtest\fP (rustc\(cqs built in unit\-test and micro\-benchmarking framework). If -you\(cqre passing arguments to both Cargo and the binary, the ones after \fB\-\-\fP go -to the binary, the ones before go to Cargo. For details about libtest\(cqs -arguments see the output of \fBcargo bench \-\- \-\-help\fP. As an example, this will -run only the benchmark named \fBfoo\fP (and skip other similarly named benchmarks -like \fBfoobar\fP): +The benchmark filtering argument \fIbenchname\fR and all the arguments following +the two dashes (\fB\-\-\fR) are passed to the benchmark binaries and thus to +\fIlibtest\fR (rustc's built in unit\-test and micro\-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after \fB\-\-\fR go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of \fBcargo bench \-\- \-\-help\fR\&. As an example, this will +run only the benchmark named \fBfoo\fR (and skip other similarly named benchmarks +like \fBfoobar\fR): .sp -.if n .RS 4 +.RS 4 .nf cargo bench \-\- foo \-\-exact .fi -.if n .RE +.RE .sp -Benchmarks are built with the \fB\-\-test\fP option to \fBrustc\fP which creates an -executable with a \fBmain\fP function that automatically runs all functions -annotated with the \fB#[bench]\fP attribute. Cargo passes the \fB\-\-bench\fP flag to +Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an +executable with a \fBmain\fR function that automatically runs all functions +annotated with the \fB#[bench]\fR attribute. Cargo passes the \fB\-\-bench\fR flag to the test harness to tell it to run only benchmarks. .sp -The libtest harness may be disabled by setting \fBharness = false\fP in the target -manifest settings, in which case your code will need to provide its own \fBmain\fP +The libtest harness may be disabled by setting \fBharness = false\fR in the target +manifest settings, in which case your code will need to provide its own \fBmain\fR function to handle running benchmarks. .RS 3 -.ll -.6i +.ll -5 .sp -\fBNote\fP: The -\c -.URL "https://doc.rust\-lang.org/nightly/unstable\-book/library\-features/test.html" "\fB#[bench]\fP attribute" +\fBNote\fR: The +\fI\f(BI#[bench]\fI attribute\fR is currently unstable and only available on the -.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel" "." +\fInightly channel\fR \&. There are some packages available on -.URL "https://crates.io/keywords/benchmark" "crates.io" " " -that may help with +\fIcrates.io\fR that may help with running benchmarks on the stable channel, such as -.URL "https://crates.io/crates/criterion" "Criterion" "." +\fICriterion\fR \&. .br .RE .ll .SH "OPTIONS" .SS "Benchmark Options" .sp -\fB\-\-no\-run\fP +\fB\-\-no\-run\fR .RS 4 -Compile, but don\(cqt run benchmarks. +Compile, but don't run benchmarks. .RE .sp -\fB\-\-no\-fail\-fast\fP +\fB\-\-no\-fail\-fast\fR .RS 4 Run all benchmarks regardless of failure. Without this flag, Cargo will exit -after the first executable fails. The Rust test harness will run all -benchmarks within the executable to completion, this flag only applies to -the executable as a whole. +after the first executable fails. The Rust test harness will run all benchmarks +within the executable to completion, this flag only applies to the executable +as a whole. .RE .SS "Package Selection" -.sp 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 -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Benchmark only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Benchmark only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Benchmark all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo bench\fP will build the +When no target selection options are given, \fBcargo bench\fR will build the following targets of the selected packages: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -lib — used to link with binaries and benchmarks +\h'-04'\(bu\h'+02'lib \[em] used to link with binaries and benchmarks .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -bins (only if benchmark targets are built and required features are +\h'-04'\(bu\h'+02'bins (only if benchmark targets are built and required features are available) .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -lib as a benchmark +\h'-04'\(bu\h'+02'lib as a benchmark .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -bins as benchmarks +\h'-04'\(bu\h'+02'bins as benchmarks .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -benchmark targets +\h'-04'\(bu\h'+02'benchmark targets .RE .sp -The default behavior can be changed by setting the \fBbench\fP flag for the target -in the manifest settings. Setting examples to \fBbench = true\fP will build and -run the example as a benchmark. Setting targets to \fBbench = false\fP will stop +The default behavior can be changed by setting the \fBbench\fR flag for the target +in the manifest settings. Setting examples to \fBbench = true\fR will build and +run the example as a benchmark. Setting targets to \fBbench = false\fR will stop them from being benchmarked by default. Target selection options that take a -target by name ignore the \fBbench\fP flag and will always benchmark the given +target by name ignore the \fBbench\fR flag and will always benchmark the given target. .sp -Passing target selection flags will benchmark only the -specified targets. +Passing target selection flags will benchmark only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Benchmark the package\(cqs library. +Benchmark the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Benchmark the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Benchmark all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Benchmark the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Benchmark all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Benchmark the specified integration test. This flag may be specified multiple -times. +Benchmark the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Benchmark all targets in test mode that have the \fBtest = true\fP manifest +Benchmark all targets in test mode that have the \fBtest = true\fR 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 \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Benchmark the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Benchmark all targets in benchmark mode that have the \fBbench = true\fP +Benchmark all targets in benchmark mode that have the \fBbench = true\fR 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 \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Benchmark all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Benchmark all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Benchmark for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" -.sp 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 -passing \fB\-\-nocapture\fP to the benchmark binaries: +passing \fB\-\-nocapture\fR to the benchmark binaries: .sp -.if n .RS 4 +.RS 4 .nf cargo bench \-\- \-\-nocapture .fi -.if n .RE +.RE .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -492,117 +360,91 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" -.sp -The \fB\-\-jobs\fP argument affects the building of the benchmark executable but +The \fB\-\-jobs\fR 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. .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" +\fIthe reference\fR for more details. .sp -Benchmarks are always built with the \fBbench\fP profile. Binary and lib targets -are built separately as benchmarks with the \fBbench\fP profile. Library targets -are built with the \fBrelease\fP profiles when linked to binaries and benchmarks. -Dependencies use the \fBrelease\fP profile. +Benchmarks are always built with the \fBbench\fR profile. Binary and lib targets +are built separately as benchmarks with the \fBbench\fR profile. Library targets +are built with the \fBrelease\fR profiles when linked to binaries and benchmarks. +Dependencies use the \fBrelease\fR profile. .sp If you need a debug build of a benchmark, try building it with -\fBcargo\-build\fP(1) which will use the \fBtest\fP profile which is by default +\fBcargo\-build\fR(1) which will use the \fBtest\fR profile which is by default unoptimized and includes debug information. You can then run the debug\-enabled benchmark manually. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Build and execute all the benchmarks of the current package: +\h'-04' 1.\h'+01'Build and execute all the benchmarks of the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo bench .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Run only a specific benchmark within a specific benchmark target: +\h'-04' 2.\h'+01'Run only a specific benchmark within a specific benchmark target: .sp -.if n .RS 4 +.RS 4 .nf cargo bench \-\-bench bench_name \-\- modname::some_benchmark .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-test\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-test\fR(1) diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index 6c331075f80..7cc100ea2b8 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -1,395 +1,296 @@ '\" t -.\" Title: cargo-build -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-BUILD" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-BUILD" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-build \- Compile the current package .SH "SYNOPSIS" -.sp -\fBcargo build [\fIOPTIONS\fP]\fP +\fBcargo build\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Compile local packages and all of their dependencies. .SH "OPTIONS" .SS "Package Selection" -.sp 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 -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Build only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Build only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Build all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo build\fP will build all +When no target selection options are given, \fBcargo build\fR will build all binary and library targets of the selected packages. Binaries are skipped if -they have \fBrequired\-features\fP that are missing. +they have \fBrequired\-features\fR that are missing. .sp -Passing target selection flags will build only the -specified targets. +Passing target selection flags will build only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Build the package\(cqs library. +Build the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Build the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Build all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Build the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Build all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Build the specified integration test. This flag may be specified multiple -times. +Build the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Build all targets in test mode that have the \fBtest = true\fP manifest +Build all targets in test mode that have the \fBtest = true\fR 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 \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Build the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Build all targets in benchmark mode that have the \fBbench = true\fP +Build all targets in benchmark mode that have the \fBbench = true\fR 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 \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Build for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Build optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Build optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .sp -\fB\-\-out\-dir\fP \fIDIRECTORY\fP +\fB\-\-out\-dir\fR \fIdirectory\fR .RS 4 Copy final artifacts to this directory. .sp This option is unstable and available only on the -\c -.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel" -and requires the \fB\-Z unstable\-options\fP flag to enable. -See \c -.URL "https://github.com/rust\-lang/cargo/issues/6790" "" " " -for more information. +\fInightly channel\fR +and requires the \fB\-Z unstable\-options\fR flag to enable. +See https://github.com/rust\-lang/cargo/issues/6790 for more information. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .sp -\fB\-\-build\-plan\fP +\fB\-\-build\-plan\fR .RS 4 -Outputs a series of JSON messages to stdout that indicate the commands to -run the build. +Outputs a series of JSON messages to stdout that indicate the commands to run +the build. .sp This option is unstable and available only on the -\c -.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel" -and requires the \fB\-Z unstable\-options\fP flag to enable. -See \c -.URL "https://github.com/rust\-lang/cargo/issues/5579" "" " " -for more information. +\fInightly channel\fR +and requires the \fB\-Z unstable\-options\fR flag to enable. +See for more information. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -399,146 +300,110 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Build the local package and all of its dependencies: +\h'-04' 1.\h'+01'Build the local package and all of its dependencies: .sp -.if n .RS 4 +.RS 4 .nf cargo build .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Build with optimizations: +\h'-04' 2.\h'+01'Build with optimizations: .sp -.if n .RS 4 +.RS 4 .nf cargo build \-\-release .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-rustc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-rustc\fR(1) diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index d31221204e0..d984658e474 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -1,381 +1,288 @@ '\" t -.\" Title: cargo-check -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-CHECK" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-CHECK" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-check \- Check the current package .SH "SYNOPSIS" -.sp -\fBcargo check [\fIOPTIONS\fP]\fP +\fBcargo check\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Check a local package and all of its dependencies for errors. This will essentially compile the packages without performing the final step of code -generation, which is faster than running \fBcargo build\fP. The compiler will save +generation, which is faster than running \fBcargo build\fR\&. The compiler will save metadata files to disk so that future runs will reuse them if the source has not been modified. .SH "OPTIONS" .SS "Package Selection" -.sp 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 -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Check only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Check only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Check all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo check\fP will check all +When no target selection options are given, \fBcargo check\fR will check all binary and library targets of the selected packages. Binaries are skipped if -they have \fBrequired\-features\fP that are missing. +they have \fBrequired\-features\fR that are missing. .sp -Passing target selection flags will check only the -specified targets. +Passing target selection flags will check only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Check the package\(cqs library. +Check the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Check the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Check all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Check the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Check all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Check the specified integration test. This flag may be specified multiple -times. +Check the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Check all targets in test mode that have the \fBtest = true\fP manifest +Check all targets in test mode that have the \fBtest = true\fR 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 \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Check the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Check all targets in benchmark mode that have the \fBbench = true\fP +Check all targets in benchmark mode that have the \fBbench = true\fR 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 \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Check all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Check all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Check for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Check optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Check optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .sp -\fB\-\-profile\fP \fINAME\fP +\fB\-\-profile\fR \fIname\fR .RS 4 -Changes check behavior. Currently only \fBtest\fP is -supported, which will check with the -\fB#[cfg(test)]\fP attribute enabled. This is useful to have it -check unit tests which are usually excluded via -the \fBcfg\fP attribute. This does not change the actual profile used. +Changes check behavior. Currently only \fBtest\fR is supported, +which will check with the \fB#[cfg(test)]\fR attribute enabled. +This is useful to have it check unit tests which are usually +excluded via the \fBcfg\fR attribute. This does not change the actual profile +used. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -385,146 +292,110 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Check the local package for errors: +\h'-04' 1.\h'+01'Check the local package for errors: .sp -.if n .RS 4 +.RS 4 .nf cargo check .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Check all targets, including unit tests: +\h'-04' 2.\h'+01'Check all targets, including unit tests: .sp -.if n .RS 4 +.RS 4 .nf cargo check \-\-all\-targets \-\-profile=test .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-clean.1 b/src/etc/man/cargo-clean.1 index 084866f7624..c9112bb0564 100644 --- a/src/etc/man/cargo-clean.1 +++ b/src/etc/man/cargo-clean.1 @@ -1,170 +1,122 @@ '\" t -.\" Title: cargo-clean -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-CLEAN" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-CLEAN" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-clean \- Remove generated artifacts .SH "SYNOPSIS" -.sp -\fBcargo clean [\fIOPTIONS\fP]\fP +\fBcargo clean\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Remove artifacts from the target directory that Cargo has generated in the past. .sp -With no options, \fBcargo clean\fP will delete the entire target directory. +With no options, \fBcargo clean\fR will delete the entire target directory. .SH "OPTIONS" .SS "Package Selection" -.sp When no packages are selected, all packages and all dependencies in the workspace are cleaned. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 Clean only the specified packages. This flag may be specified -multiple times. See \fBcargo\-pkgid\fP(1) for the SPEC format. +multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format. .RE .SS "Clean Options" .sp -\fB\-\-doc\fP +\fB\-\-doc\fR .RS 4 -This option will cause \fBcargo clean\fP to remove only the \fBdoc\fP directory in +This option will cause \fBcargo clean\fR to remove only the \fBdoc\fR directory in the target directory. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Clean all artifacts that were built with the \fBrelease\fP or \fBbench\fP -profiles. +Clean all artifacts that were built with the \fBrelease\fR or \fBbench\fR profiles. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Clean for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -174,86 +126,64 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Remove the entire target directory: +\h'-04' 1.\h'+01'Remove the entire target directory: .sp -.if n .RS 4 +.RS 4 .nf cargo clean .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Remove only the release artifacts: +\h'-04' 2.\h'+01'Remove only the release artifacts: .sp -.if n .RS 4 +.RS 4 .nf cargo clean \-\-release .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 136e689b08b..93e1534a595 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -1,340 +1,247 @@ '\" t -.\" Title: cargo-doc -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-04-21 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-DOC" "1" "2020-04-21" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-DOC" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" -cargo\-doc \- Build a package\(aqs documentation +cargo\-doc \- Build a package's documentation .SH "SYNOPSIS" -.sp -\fBcargo doc [\fIOPTIONS\fP]\fP +\fBcargo doc\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Build the documentation for the local package and all dependencies. The output -is placed in \fBtarget/doc\fP in rustdoc\(cqs usual format. +is placed in \fBtarget/doc\fR in rustdoc's usual format. .SH "OPTIONS" .SS "Documentation Options" .sp -\fB\-\-open\fP +\fB\-\-open\fR .RS 4 Open the docs in a browser after building them. This will use your default -browser unless you define another one in the \fBBROWSER\fP environment -variable. +browser unless you define another one in the \fBBROWSER\fR environment variable. .RE .sp -\fB\-\-no\-deps\fP +\fB\-\-no\-deps\fR .RS 4 Do not build documentation for dependencies. .RE .sp -\fB\-\-document\-private\-items\fP +\fB\-\-document\-private\-items\fR .RS 4 Include non\-public items in the documentation. .RE .SS "Package Selection" -.sp 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 -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Document only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Document only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Document all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo doc\fP will document all +When no target selection options are given, \fBcargo doc\fR 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 -\fBrequired\-features\fP that are missing. +\fBrequired\-features\fR that are missing. .sp -The default behavior can be changed by setting \fBdoc = false\fP for the target in -the manifest settings. Using target selection options will ignore the \fBdoc\fP +The default behavior can be changed by setting \fBdoc = false\fR for the target in +the manifest settings. Using target selection options will ignore the \fBdoc\fR flag and will always document the given target. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Document the package\(cqs library. +Document the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Document the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Document all binary targets. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Document for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Document optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Document optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -344,130 +251,101 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Build the local package documentation and its dependencies and output to -\fBtarget/doc\fP. +\h'-04' 1.\h'+01'Build the local package documentation and its dependencies and output to +\fBtarget/doc\fR\&. .sp -.if n .RS 4 +.RS 4 .nf cargo doc .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-rustdoc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-rustdoc\fR(1), \fBrustdoc\fR(1) diff --git a/src/etc/man/cargo-fetch.1 b/src/etc/man/cargo-fetch.1 index 0a4225de40e..b2e798ec31b 100644 --- a/src/etc/man/cargo-fetch.1 +++ b/src/etc/man/cargo-fetch.1 @@ -1,148 +1,101 @@ '\" t -.\" Title: cargo-fetch -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-11-11 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-FETCH" "1" "2019-11-11" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-FETCH" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-fetch \- Fetch dependencies of a package from the network .SH "SYNOPSIS" -.sp -\fBcargo fetch [\fIOPTIONS\fP]\fP +\fBcargo fetch\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -If a \fBCargo.lock\fP file is available, this command will ensure that all of the +If a \fBCargo.lock\fR file is available, this command will ensure that all of the git dependencies and/or registry dependencies are downloaded and locally -available. Subsequent Cargo commands never touch the network after a \fBcargo -fetch\fP unless the lock file changes. +available. Subsequent Cargo commands never touch the network after a \fBcargo fetch\fR unless the lock file changes. .sp If the lock file is not available, then this command will generate the lock file before fetching the dependencies. .sp -If \fB\-\-target\fP is not specified, then all target dependencies are fetched. +If \fB\-\-target\fR is not specified, then all target dependencies are fetched. .sp -See also the \c -.URL "https://crates.io/crates/cargo\-prefetch" "cargo\-prefetch" +See also the \fIcargo\-prefetch\fR plugin which adds a command to download popular crates. This may be useful if -you plan to use Cargo without a network with the \fB\-\-offline\fP flag. +you plan to use Cargo without a network with the \fB\-\-offline\fR flag. .SH "OPTIONS" .SS "Fetch options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Fetch for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -152,69 +105,54 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Fetch all dependencies: +\h'-04' 1.\h'+01'Fetch all dependencies: .sp -.if n .RS 4 +.RS 4 .nf cargo fetch .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-update\fP(1), \fBcargo\-generate\-lockfile\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-update\fR(1), \fBcargo\-generate\-lockfile\fR(1) diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index 9a29b4a0048..6df87b542b7 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -1,455 +1,362 @@ '\" t -.\" Title: cargo-fix -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-FIX" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-FIX" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-fix \- Automatically fix lint warnings reported by rustc .SH "SYNOPSIS" -.sp -\fBcargo fix [\fIOPTIONS\fP]\fP +\fBcargo fix\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This Cargo subcommand will automatically take rustc\(cqs suggestions from +This Cargo subcommand will automatically take rustc's suggestions from diagnostics like warnings and apply them to your source code. This is intended to help automate tasks that rustc itself already knows how to tell you to fix! -The \fBcargo fix\fP subcommand is also being developed for the Rust 2018 edition +The \fBcargo fix\fR 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. .sp -Executing \fBcargo fix\fP will under the hood execute \fBcargo\-check\fP(1). Any warnings +Executing \fBcargo fix\fR will under the hood execute \fBcargo\-check\fR(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\(cqd like to prepare for the 2018 edition, you can do so by +example if you'd like to prepare for the 2018 edition, you can do so by executing: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition .fi -.if n .RE +.RE .sp -which behaves the same as \fBcargo check \-\-all\-targets\fP. +which behaves the same as \fBcargo check \-\-all\-targets\fR\&. .sp -\fBcargo fix\fP is only capable of fixing code that is normally compiled with -\fBcargo check\fP. If code is conditionally enabled with optional features, you +\fBcargo fix\fR is only capable of fixing code that is normally compiled with +\fBcargo check\fR\&. If code is conditionally enabled with optional features, you will need to enable those features for that code to be analyzed: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition \-\-features foo .fi -.if n .RE +.RE .sp -Similarly, other \fBcfg\fP expressions like platform\-specific code will need to -pass \fB\-\-target\fP to fix code for the given target. +Similarly, other \fBcfg\fR expressions like platform\-specific code will need to +pass \fB\-\-target\fR to fix code for the given target. .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu .fi -.if n .RE +.RE .sp -If you encounter any problems with \fBcargo fix\fP or otherwise have any questions -or feature requests please don\(cqt hesitate to file an issue at -.URL "https://github.com/rust\-lang/cargo" "" "" +If you encounter any problems with \fBcargo fix\fR or otherwise have any questions +or feature requests please don't hesitate to file an issue at + .SH "OPTIONS" .SS "Fix options" .sp -\fB\-\-broken\-code\fP +\fB\-\-broken\-code\fR .RS 4 -Fix code even if it already has compiler errors. This is useful if \fBcargo -fix\fP 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. +Fix code even if it already has compiler errors. This is useful if \fBcargo fix\fR +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. .RE .sp -\fB\-\-edition\fP +\fB\-\-edition\fR .RS 4 -Apply changes that will update the code to the latest edition. This will -not update the edition in the \fBCargo.toml\fP manifest, which must be updated +Apply changes that will update the code to the latest edition. This will not +update the edition in the \fBCargo.toml\fR manifest, which must be updated manually. .RE .sp -\fB\-\-edition\-idioms\fP +\fB\-\-edition\-idioms\fR .RS 4 -Apply suggestions that will update code to the preferred style for the -current edition. +Apply suggestions that will update code to the preferred style for the current +edition. .RE .sp -\fB\-\-allow\-no\-vcs\fP +\fB\-\-allow\-no\-vcs\fR .RS 4 Fix code even if a VCS was not detected. .RE .sp -\fB\-\-allow\-dirty\fP +\fB\-\-allow\-dirty\fR .RS 4 Fix code even if the working directory has changes. .RE .sp -\fB\-\-allow\-staged\fP +\fB\-\-allow\-staged\fR .RS 4 Fix code even if the working directory has staged changes. .RE .SS "Package Selection" -.sp 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 -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Fix only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Fix only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Fix all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Target Selection" +When no target selection options are given, \fBcargo fix\fR will fix all targets +(\fB\-\-all\-targets\fR implied). Binaries are skipped if they have +\fBrequired\-features\fR that are missing. .sp -When no target selection options are given, \fBcargo fix\fP will fix all targets -(\fB\-\-all\-targets\fP implied). Binaries are skipped if they have -\fBrequired\-features\fP that are missing. +Passing target selection flags will fix only the specified +targets. .sp -Passing target selection flags will fix only the -specified targets. -.sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Fix the package\(cqs library. +Fix the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Fix the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Fix all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Fix the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Fix all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Fix the specified integration test. This flag may be specified multiple -times. +Fix the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Fix all targets in test mode that have the \fBtest = true\fP manifest +Fix all targets in test mode that have the \fBtest = true\fR 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 \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Fix the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Fix all targets in benchmark mode that have the \fBbench = true\fP +Fix all targets in benchmark mode that have the \fBbench = true\fR 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 \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Fix all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Fix all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Fix for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Fix optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Fix optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .sp -\fB\-\-profile\fP \fINAME\fP +\fB\-\-profile\fR \fIname\fR .RS 4 -Changes fix behavior. Currently only \fBtest\fP is -supported, which will fix with the -\fB#[cfg(test)]\fP attribute enabled. This is useful to have it -fix unit tests which are usually excluded via -the \fBcfg\fP attribute. This does not change the actual profile used. +Changes fix behavior. Currently only \fBtest\fR is supported, +which will fix with the \fB#[cfg(test)]\fR attribute enabled. +This is useful to have it fix unit tests which are usually +excluded via the \fBcfg\fR attribute. This does not change the actual profile +used. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -459,163 +366,120 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Apply compiler suggestions to the local package: +\h'-04' 1.\h'+01'Apply compiler suggestions to the local package: .sp -.if n .RS 4 +.RS 4 .nf cargo fix .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Convert a 2015 edition to 2018: +\h'-04' 2.\h'+01'Convert a 2015 edition to 2018: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Apply suggested idioms for the current edition: +\h'-04' 3.\h'+01'Apply suggested idioms for the current edition: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition\-idioms .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-check\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-check\fR(1) diff --git a/src/etc/man/cargo-generate-lockfile.1 b/src/etc/man/cargo-generate-lockfile.1 index 23bb1110b73..8e714a0d5da 100644 --- a/src/etc/man/cargo-generate-lockfile.1 +++ b/src/etc/man/cargo-generate-lockfile.1 @@ -1,123 +1,79 @@ '\" t -.\" Title: cargo-generate-lockfile -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-GENERATE\-LOCKFILE" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-GENERATE\-LOCKFILE" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-generate\-lockfile \- Generate the lockfile for a package .SH "SYNOPSIS" -.sp -\fBcargo generate\-lockfile [\fIOPTIONS\fP]\fP +\fBcargo generate\-lockfile\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This command will create the \fBCargo.lock\fP lockfile for the current package or +This command will create the \fBCargo.lock\fR 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. .sp -See also \fBcargo\-update\fP(1) which is also capable of creating a \fBCargo.lock\fP +See also \fBcargo\-update\fR(1) which is also capable of creating a \fBCargo.lock\fR lockfile and has more options for controlling update behavior. .SH "OPTIONS" .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -127,69 +83,54 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Create or update the lockfile for the current package or workspace: +\h'-04' 1.\h'+01'Create or update the lockfile for the current package or workspace: .sp -.if n .RS 4 +.RS 4 .nf cargo generate\-lockfile .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-update\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-update\fR(1) diff --git a/src/etc/man/cargo-help.1 b/src/etc/man/cargo-help.1 index bcff591d531..8ff0ad22e49 100644 --- a/src/etc/man/cargo-help.1 +++ b/src/etc/man/cargo-help.1 @@ -1,75 +1,34 @@ '\" t -.\" Title: cargo-help -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-HELP" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-HELP" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-help \- Get help for a Cargo command .SH "SYNOPSIS" -.sp -\fBcargo help [\fISUBCOMMAND\fP]\fP +\fBcargo help\fR [\fIsubcommand\fR] .SH "DESCRIPTION" -.sp Prints a help message for the given command. .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Get help for a command: +\h'-04' 1.\h'+01'Get help for a command: .sp -.if n .RS 4 +.RS 4 .nf cargo help build .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Help is also available with the \fB\-\-help\fP flag: +\h'-04' 2.\h'+01'Help is also available with the \fB\-\-help\fR flag: .sp -.if n .RS 4 +.RS 4 .nf cargo build \-\-help .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) \ No newline at end of file +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-init.1 b/src/etc/man/cargo-init.1 index f1189c74c5f..c0f5f2e8243 100644 --- a/src/etc/man/cargo-init.1 +++ b/src/etc/man/cargo-init.1 @@ -1,374 +1,214 @@ '\" t -.\" Title: cargo-init -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-INIT" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-INIT" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-init \- Create a new Cargo package in an existing directory .SH "SYNOPSIS" -.sp -\fBcargo init [\fIOPTIONS\fP] [\fIPATH\fP]\fP +\fBcargo init\fR [\fIoptions\fR] [\fIpath\fR] .SH "DESCRIPTION" -.sp This command will create a new Cargo manifest in the current directory. Give a path as an argument to create in the given directory. .sp If there are typically\-named Rust source files already in the directory, those -will be used. If not, then a sample \fBsrc/main.rs\fP file will be created, or -\fBsrc/lib.rs\fP if \fB\-\-lib\fP is passed. +will be used. If not, then a sample \fBsrc/main.rs\fR file will be created, or +\fBsrc/lib.rs\fR if \fB\-\-lib\fR is passed. .sp If the directory is not already in a VCS repository, then a new repository -is created (see \fB\-\-vcs\fP below). +is created (see \fB\-\-vcs\fR below). .sp The "authors" field in the manifest is determined from the environment or configuration settings. A name is required and is determined from (first match wins): .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBcargo\-new.name\fP Cargo config value +\h'-04'\(bu\h'+02'\fBcargo\-new.name\fR Cargo config value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_NAME\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_NAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_AUTHOR_NAME\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_NAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_COMMITTER_NAME\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_NAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBuser.name\fP git configuration value +\h'-04'\(bu\h'+02'\fBuser.name\fR git configuration value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBUSER\fP environment variable +\h'-04'\(bu\h'+02'\fBUSER\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBUSERNAME\fP environment variable +\h'-04'\(bu\h'+02'\fBUSERNAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBNAME\fP environment variable +\h'-04'\(bu\h'+02'\fBNAME\fR environment variable .RE .sp The email address is optional and is determined from: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBcargo\-new.email\fP Cargo config value +\h'-04'\(bu\h'+02'\fBcargo\-new.email\fR Cargo config value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_EMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_EMAIL\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_AUTHOR_EMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_EMAIL\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_COMMITTER_EMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_EMAIL\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBuser.email\fP git configuration value +\h'-04'\(bu\h'+02'\fBuser.email\fR git configuration value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBEMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBEMAIL\fR environment variable .RE .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" " " -for more information about +See \fIthe reference\fR for more information about configuration files. .sp -See \fBcargo\-new\fP(1) for a similar command which will create a new package in +See \fBcargo\-new\fR(1) for a similar command which will create a new package in a new directory. .SH "OPTIONS" .SS "Init Options" .sp -\fB\-\-bin\fP +\fB\-\-bin\fR .RS 4 -Create a package with a binary target (\fBsrc/main.rs\fP). +Create a package with a binary target (\fBsrc/main.rs\fR). This is the default behavior. .RE .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Create a package with a library target (\fBsrc/lib.rs\fP). +Create a package with a library target (\fBsrc/lib.rs\fR). .RE .sp -\fB\-\-edition\fP \fIEDITION\fP +\fB\-\-edition\fR \fIedition\fR .RS 4 Specify the Rust edition to use. Default is 2018. Possible values: 2015, 2018 .RE .sp -\fB\-\-name\fP \fINAME\fP +\fB\-\-name\fR \fIname\fR .RS 4 Set the package name. Defaults to the directory name. .RE .sp -\fB\-\-vcs\fP \fIVCS\fP +\fB\-\-vcs\fR \fIvcs\fR .RS 4 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 \fBgit\fP or the configuration value -\fBcargo\-new.vcs\fP, or \fBnone\fP if already inside a VCS repository. +(none). If not specified, defaults to \fBgit\fR or the configuration value +\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name +This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name which will restrict publishing only to that registry. .sp -Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry defined by the \fBregistry.default\fP -config key is used. If the default registry is not set and \fB\-\-registry\fP is not -used, the \fBpublish\fP field will not be set which means that publishing will not +Registry names are defined in \fICargo config files\fR \&. +If not specified, the default registry defined by the \fBregistry.default\fR +config key is used. If the default registry is not set and \fB\-\-registry\fR is not +used, the \fBpublish\fR field will not be set which means that publishing will not be restricted. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Create a binary Cargo package in the current directory: +\h'-04' 1.\h'+01'Create a binary Cargo package in the current directory: .sp -.if n .RS 4 +.RS 4 .nf cargo init .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-new\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-new\fR(1) diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 7501ddef2f5..10d24e0f606 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -1,119 +1,57 @@ '\" t -.\" Title: cargo-install -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-07-01 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-INSTALL" "1" "2020-07-01" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-INSTALL" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-install \- Build and install a Rust binary .SH "SYNOPSIS" -.sp -\fBcargo install [\fIOPTIONS\fP] \fICRATE\fP...\fP +\fBcargo install\fR [\fIoptions\fR] \fIcrate\fR\&... .br -\fBcargo install [\fIOPTIONS\fP] \-\-path \fIPATH\fP\fP +\fBcargo install\fR [\fIoptions\fR] \fB\-\-path\fR \fIpath\fR .br -\fBcargo install [\fIOPTIONS\fP] \-\-git \fIURL\fP [\fICRATE\fP...]\fP +\fBcargo install\fR [\fIoptions\fR] \fB\-\-git\fR \fIurl\fR [\fIcrate\fR\&...] .br -\fBcargo install [\fIOPTIONS\fP] \-\-list\fP +\fBcargo install\fR [\fIoptions\fR] \fB\-\-list\fR .SH "DESCRIPTION" -.sp -This command manages Cargo\(cqs local set of installed binary crates. Only -packages which have executable \fB[[bin]]\fP or \fB[[example]]\fP targets can be -installed, and all executables are installed into the installation root\(cqs -\fBbin\fP folder. +This command manages Cargo's local set of installed binary crates. Only +packages which have executable \fB[[bin]]\fR or \fB[[example]]\fR targets can be +installed, and all executables are installed into the installation root's +\fBbin\fR folder. .sp The installation root is determined, in order of precedence: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB\-\-root\fP option +\h'-04'\(bu\h'+02'\fB\-\-root\fR option .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_INSTALL_ROOT\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBinstall.root\fP Cargo \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "" +\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_HOME\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB$HOME/.cargo\fP +\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR .RE .sp There are multiple sources from which a crate can be installed. The default -location is crates.io but the \fB\-\-git\fP, \fB\-\-path\fP, and \fB\-\-registry\fP flags can +location is crates.io but the \fB\-\-git\fR, \fB\-\-path\fR, and \fB\-\-registry\fR 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 \fICRATE\fP argument is +crates.io or a git repository with multiple crates) the \fIcrate\fR argument is required to indicate which crate should be installed. .sp Crates from crates.io can optionally specify the version they wish to install -via the \fB\-\-version\fP flags, and similarly packages from git repositories can +via the \fB\-\-version\fR flags, and similarly packages from git repositories can optionally specify the branch, tag, or revision that should be installed. If a -crate has multiple binaries, the \fB\-\-bin\fP argument can selectively install only -one of them, and if you\(cqd rather install examples the \fB\-\-example\fP argument can +crate has multiple binaries, the \fB\-\-bin\fR argument can selectively install only +one of them, and if you'd rather install examples the \fB\-\-example\fR argument can be used as well. .sp If the package is already installed, Cargo will reinstall it if the installed @@ -121,259 +59,220 @@ version does not appear to be up\-to\-date. If any of the following values change, then Cargo will reinstall the package: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The package version and source. +\h'-04'\(bu\h'+02'The package version and source. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The set of binary names installed. +\h'-04'\(bu\h'+02'The set of binary names installed. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The chosen features. +\h'-04'\(bu\h'+02'The chosen features. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The release mode (\fB\-\-debug\fP). +\h'-04'\(bu\h'+02'The release mode (\fB\-\-debug\fR). .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The target (\fB\-\-target\fP). +\h'-04'\(bu\h'+02'The target (\fB\-\-target\fR). .RE .sp -Installing with \fB\-\-path\fP will always build and install, unless there are -conflicting binaries from another package. The \fB\-\-force\fP flag may be used to +Installing with \fB\-\-path\fR will always build and install, unless there are +conflicting binaries from another package. The \fB\-\-force\fR flag may be used to force Cargo to always reinstall the package. .sp -If the source is crates.io or \fB\-\-git\fP then by default the crate will be built +If the source is crates.io or \fB\-\-git\fR then by default the crate will be built in a temporary target directory. To avoid this, the target directory can be -specified by setting the \fBCARGO_TARGET_DIR\fP environment variable to a relative +specified by setting the \fBCARGO_TARGET_DIR\fR environment variable to a relative path. In particular, this can be useful for caching build artifacts on continuous integration systems. .sp -By default, the \fBCargo.lock\fP file that is included with the package will be +By default, the \fBCargo.lock\fR file that is included with the package will be ignored. This means that Cargo will recompute which versions of dependencies to use, possibly using newer versions that have been released since the -package was published. The \fB\-\-locked\fP flag can be used to force Cargo to use -the packaged \fBCargo.lock\fP file if it is available. This may be useful for +package was published. The \fB\-\-locked\fR flag can be used to force Cargo to use +the packaged \fBCargo.lock\fR file if it is available. This may be useful for ensuring reproducible builds, to use the exact same set of dependencies that were available when the package was published. It may also be useful if a newer version of a dependency is published that no longer builds on your -system, or has other problems. The downside to using \fB\-\-locked\fP is that you +system, or has other problems. The downside to using \fB\-\-locked\fR is that you will not receive any fixes or updates to any dependency. Note that Cargo did -not start publishing \fBCargo.lock\fP files until version 1.37, which means -packages published with prior versions will not have a \fBCargo.lock\fP file +not start publishing \fBCargo.lock\fR files until version 1.37, which means +packages published with prior versions will not have a \fBCargo.lock\fR file available. .SH "OPTIONS" .SS "Install Options" .sp -\fB\-\-vers\fP \fIVERSION\fP, \fB\-\-version\fP \fIVERSION\fP +\fB\-\-vers\fR \fIversion\fR, +\fB\-\-version\fR \fIversion\fR .RS 4 -Specify a version to install. This may be a -.URL "https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.md" "version requirement" "," -like -\fB~1.2\fP, to have Cargo select the newest version from the given -requirement. If the version does not have a requirement operator (such as -\fB^\fP or \fB~\fP), then it must be in the form \fIMAJOR.MINOR.PATCH\fP, and will -install exactly that version; it is \fBnot\fP treated as a caret requirement -like Cargo dependencies are. +Specify a version to install. This may be a \fIversion +requirement\fR , like \fB~1.2\fR, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as \fB^\fR or \fB~\fR), then it must be in the form +\fIMAJOR.MINOR.PATCH\fR, and will install exactly that version; it is \fInot\fR +treated as a caret requirement like Cargo dependencies are. .RE .sp -\fB\-\-git\fP \fIURL\fP +\fB\-\-git\fR \fIurl\fR .RS 4 Git URL to install the specified crate from. .RE .sp -\fB\-\-branch\fP \fIBRANCH\fP +\fB\-\-branch\fR \fIbranch\fR .RS 4 Branch to use when installing from git. .RE .sp -\fB\-\-tag\fP \fITAG\fP +\fB\-\-tag\fR \fItag\fR .RS 4 Tag to use when installing from git. .RE .sp -\fB\-\-rev\fP \fISHA\fP +\fB\-\-rev\fR \fIsha\fR .RS 4 Specific commit to use when installing from git. .RE .sp -\fB\-\-path\fP \fIPATH\fP +\fB\-\-path\fR \fIpath\fR .RS 4 Filesystem path to local crate to install. .RE .sp -\fB\-\-list\fP +\fB\-\-list\fR .RS 4 List all installed packages and their versions. .RE .sp -\fB\-f\fP, \fB\-\-force\fP +\fB\-f\fR, +\fB\-\-force\fR .RS 4 -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 \fBrustc\fP. +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 \fBrustc\fR\&. .RE .sp -\fB\-\-no\-track\fP +\fB\-\-no\-track\fR .RS 4 -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 \fB\-\-force\fP flag is used. This also disables -Cargo\(cqs ability to protect against multiple concurrent invocations of -Cargo installing at the same time. +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 \fB\-\-force\fR flag is used. This also disables Cargo's ability to +protect against multiple concurrent invocations of Cargo installing at the +same time. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Install only the specified binary. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Install all binaries. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Install only the specified example. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Install all examples. .RE .sp -\fB\-\-root\fP \fIDIR\fP +\fB\-\-root\fR \fIdir\fR .RS 4 Directory to install packages into. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Install for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .sp -\fB\-\-debug\fP +\fB\-\-debug\fR .RS 4 -Build with the \fBdev\fP profile instead the \fBrelease\fP profile. +Build with the \fBdev\fR profile instead the \fBrelease\fR profile. .RE .SS "Manifest Options" .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -383,169 +282,120 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Install or upgrade a package from crates.io: +\h'-04' 1.\h'+01'Install or upgrade a package from crates.io: .sp -.if n .RS 4 +.RS 4 .nf cargo install ripgrep .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Install or reinstall the package in the current directory: +\h'-04' 2.\h'+01'Install or reinstall the package in the current directory: .sp -.if n .RS 4 +.RS 4 .nf cargo install \-\-path . .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -View the list of installed packages: +\h'-04' 3.\h'+01'View the list of installed packages: .sp -.if n .RS 4 +.RS 4 .nf cargo install \-\-list .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-uninstall\fP(1), \fBcargo\-search\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-uninstall\fR(1), \fBcargo\-search\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-locate-project.1 b/src/etc/man/cargo-locate-project.1 index 4a73aed7c35..29283dde5ac 100644 --- a/src/etc/man/cargo-locate-project.1 +++ b/src/etc/man/cargo-locate-project.1 @@ -1,165 +1,106 @@ '\" t -.\" Title: cargo-locate-project -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-LOCATE\-PROJECT" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-LOCATE\-PROJECT" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" -cargo\-locate\-project \- Print a JSON representation of a Cargo.toml file\(aqs location +cargo\-locate\-project \- Print a JSON representation of a Cargo.toml file's location .SH "SYNOPSIS" -.sp -\fBcargo locate\-project [\fIOPTIONS\fP]\fP +\fBcargo locate\-project\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp This command will print a JSON object to stdout with the full path to the -\fBCargo.toml\fP manifest. +\fBCargo.toml\fR manifest. .sp -See also \fBcargo\-metadata\fP(1) which is capable of returning the path to a +See also \fBcargo\-metadata\fR(1) which is capable of returning the path to a workspace root. .SH "OPTIONS" .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Display the path to the manifest based on the current directory: -.sp -.if n .RS 4 +\h'-04' 1.\h'+01'Display the path to the manifest based on the current directory: +.sp +.RS 4 .nf cargo locate\-project .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-login.1 b/src/etc/man/cargo-login.1 index 1ac847fb566..87129c1f5ff 100644 --- a/src/etc/man/cargo-login.1 +++ b/src/etc/man/cargo-login.1 @@ -1,173 +1,113 @@ '\" t -.\" Title: cargo-login -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-LOGIN" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-LOGIN" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-login \- Save an API token from the registry locally .SH "SYNOPSIS" -.sp -\fBcargo login [\fIOPTIONS\fP] [\fITOKEN\fP]\fP +\fBcargo login\fR [\fIoptions\fR] [\fItoken\fR] .SH "DESCRIPTION" -.sp This command will save the API token to disk so that commands that require -authentication, such as \fBcargo\-publish\fP(1), will be automatically -authenticated. The token is saved in \fB$CARGO_HOME/credentials.toml\fP. \fBCARGO_HOME\fP -defaults to \fB.cargo\fP in your home directory. +authentication, such as \fBcargo\-publish\fR(1), will be automatically +authenticated. The token is saved in \fB$CARGO_HOME/credentials.toml\fR\&. \fBCARGO_HOME\fR +defaults to \fB\&.cargo\fR in your home directory. .sp -If the \fITOKEN\fP argument is not specified, it will be read from stdin. +If the \fItoken\fR argument is not specified, it will be read from stdin. .sp -The API token for crates.io may be retrieved from \c -.URL "https://crates.io/me" "" "." +The API token for crates.io may be retrieved from \&. .sp Take care to keep the token secret, it should not be shared with anyone else. .SH "OPTIONS" .SS "Login Options" .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Save the API token to disk: -.sp -.if n .RS 4 +\h'-04' 1.\h'+01'Save the API token to disk: +.sp +.RS 4 .nf cargo login .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 index 21cee8dfd92..3c0770ab5cc 100644 --- a/src/etc/man/cargo-metadata.1 +++ b/src/etc/man/cargo-metadata.1 @@ -1,53 +1,27 @@ '\" t -.\" Title: cargo-metadata -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-07-04 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-METADATA" "1" "2020-07-04" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-METADATA" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 +.sp +:source\-highlighter: highlightjs .SH "NAME" cargo\-metadata \- Machine\-readable metadata about the current package .SH "SYNOPSIS" -.sp -\fBcargo metadata [\fIOPTIONS\fP]\fP +\fBcargo metadata\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Output JSON to stdout containing information about the workspace members and resolved dependencies of the current package. .sp -It is recommended to include the \fB\-\-format\-version\fP flag to future\-proof +It is recommended to include the \fB\-\-format\-version\fR flag to future\-proof your code to ensure the output is in the format you are expecting. .sp -See the \c -.URL "https://crates.io/crates/cargo_metadata" "cargo_metadata crate" +See the \fIcargo_metadata crate\fR for a Rust API for reading the metadata. .SH "OUTPUT FORMAT" -.sp The output has the following format: .sp -.if n .RS 4 +.RS 4 .nf { /* Array of all packages in the workspace. @@ -77,7 +51,7 @@ The output has the following format: Example: "git+https://github.com/rust\-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" */ "source": null, - /* Array of dependencies declared in the package\(aqs manifest. */ + /* Array of dependencies declared in the package's manifest. */ "dependencies": [ { /* The name of the dependency. */ @@ -156,8 +130,7 @@ The output has the following format: the target is compatible with doc testing. */ "doctest": false, - /* Whether or not this target has the `test` field set in the manifest, - causing it to be compiled with `--test`. + /* Whether or not this target should be built and run with `\-\-test` */ "test": true } @@ -173,7 +146,7 @@ The output has the following format: "feat1": [], "feat2": [] }, - /* Absolute path to this package\(aqs manifest. */ + /* Absolute path to this package's manifest. */ "manifest_path": "/path/to/my\-package/Cargo.toml", /* Package metadata. This is null if no metadata is specified. @@ -251,7 +224,7 @@ The output has the following format: */ "deps": [ { - /* The name of the dependency\(aqs library target. + /* The name of the dependency's library target. If this is a renamed dependency, this is the new name. */ @@ -304,137 +277,117 @@ The output has the following format: } } .fi -.if n .RE +.RE .SH "OPTIONS" .SS "Output Options" .sp -\fB\-\-no\-deps\fP +\fB\-\-no\-deps\fR .RS 4 -Output information only about the workspace members and don\(cqt fetch +Output information only about the workspace members and don't fetch dependencies. .RE .sp -\fB\-\-format\-version\fP \fIVERSION\fP +\fB\-\-format\-version\fR \fIversion\fR .RS 4 -Specify the version of the output format to use. Currently \fB1\fP is the only +Specify the version of the output format to use. Currently \fB1\fR is the only possible value. .RE .sp -\fB\-\-filter\-platform\fP \fITRIPLE\fP +\fB\-\-filter\-platform\fR \fItriple\fR .RS 4 -This filters the \fBresolve\fP output to only include dependencies for the +This filters the \fBresolve\fR output to only include dependencies for the given target triple. Without this flag, the resolve includes all targets. .sp 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 \fBCargo.toml\fP. +reproduction of the information within \fBCargo.toml\fR\&. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -444,69 +397,54 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Output JSON about the current package: -.sp -.if n .RS 4 +\h'-04' 1.\h'+01'Output JSON about the current package: +.sp +.RS 4 .nf cargo metadata \-\-format\-version=1 .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-new.1 b/src/etc/man/cargo-new.1 index 68eb8750d6f..02eeb6aeb8c 100644 --- a/src/etc/man/cargo-new.1 +++ b/src/etc/man/cargo-new.1 @@ -1,369 +1,209 @@ '\" t -.\" Title: cargo-new -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-NEW" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-NEW" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-new \- Create a new Cargo package .SH "SYNOPSIS" -.sp -\fBcargo new [\fIOPTIONS\fP] \fIPATH\fP\fP +\fBcargo new\fR [\fIoptions\fR] \fIpath\fR .SH "DESCRIPTION" -.sp This command will create a new Cargo package in the given directory. This -includes a simple template with a \fBCargo.toml\fP manifest, sample source file, +includes a simple template with a \fBCargo.toml\fR 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 \fB\-\-vcs\fP below). +then a new repository is created (see \fB\-\-vcs\fR below). .sp The "authors" field in the manifest is determined from the environment or configuration settings. A name is required and is determined from (first match wins): .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBcargo\-new.name\fP Cargo config value +\h'-04'\(bu\h'+02'\fBcargo\-new.name\fR Cargo config value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_NAME\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_NAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_AUTHOR_NAME\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_NAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_COMMITTER_NAME\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_NAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBuser.name\fP git configuration value +\h'-04'\(bu\h'+02'\fBuser.name\fR git configuration value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBUSER\fP environment variable +\h'-04'\(bu\h'+02'\fBUSER\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBUSERNAME\fP environment variable +\h'-04'\(bu\h'+02'\fBUSERNAME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBNAME\fP environment variable +\h'-04'\(bu\h'+02'\fBNAME\fR environment variable .RE .sp The email address is optional and is determined from: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBcargo\-new.email\fP Cargo config value +\h'-04'\(bu\h'+02'\fBcargo\-new.email\fR Cargo config value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_EMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_EMAIL\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_AUTHOR_EMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_EMAIL\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBGIT_COMMITTER_EMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_EMAIL\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBuser.email\fP git configuration value +\h'-04'\(bu\h'+02'\fBuser.email\fR git configuration value .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBEMAIL\fP environment variable +\h'-04'\(bu\h'+02'\fBEMAIL\fR environment variable .RE .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" " " -for more information about +See \fIthe reference\fR for more information about configuration files. .sp -See \fBcargo\-init\fP(1) for a similar command which will create a new manifest +See \fBcargo\-init\fR(1) for a similar command which will create a new manifest in an existing directory. .SH "OPTIONS" .SS "New Options" .sp -\fB\-\-bin\fP +\fB\-\-bin\fR .RS 4 -Create a package with a binary target (\fBsrc/main.rs\fP). +Create a package with a binary target (\fBsrc/main.rs\fR). This is the default behavior. .RE .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Create a package with a library target (\fBsrc/lib.rs\fP). +Create a package with a library target (\fBsrc/lib.rs\fR). .RE .sp -\fB\-\-edition\fP \fIEDITION\fP +\fB\-\-edition\fR \fIedition\fR .RS 4 Specify the Rust edition to use. Default is 2018. Possible values: 2015, 2018 .RE .sp -\fB\-\-name\fP \fINAME\fP +\fB\-\-name\fR \fIname\fR .RS 4 Set the package name. Defaults to the directory name. .RE .sp -\fB\-\-vcs\fP \fIVCS\fP +\fB\-\-vcs\fR \fIvcs\fR .RS 4 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 \fBgit\fP or the configuration value -\fBcargo\-new.vcs\fP, or \fBnone\fP if already inside a VCS repository. +(none). If not specified, defaults to \fBgit\fR or the configuration value +\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name +This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name which will restrict publishing only to that registry. .sp -Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry defined by the \fBregistry.default\fP -config key is used. If the default registry is not set and \fB\-\-registry\fP is not -used, the \fBpublish\fP field will not be set which means that publishing will not +Registry names are defined in \fICargo config files\fR \&. +If not specified, the default registry defined by the \fBregistry.default\fR +config key is used. If the default registry is not set and \fB\-\-registry\fR is not +used, the \fBpublish\fR field will not be set which means that publishing will not be restricted. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Create a binary Cargo package in the given directory: +\h'-04' 1.\h'+01'Create a binary Cargo package in the given directory: .sp -.if n .RS 4 +.RS 4 .nf cargo new foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-init\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-init\fR(1) diff --git a/src/etc/man/cargo-owner.1 b/src/etc/man/cargo-owner.1 index 8df4f1d8c3a..81a25f522a2 100644 --- a/src/etc/man/cargo-owner.1 +++ b/src/etc/man/cargo-owner.1 @@ -1,248 +1,175 @@ '\" t -.\" Title: cargo-owner -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-OWNER" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-OWNER" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-owner \- Manage the owners of a crate on the registry .SH "SYNOPSIS" -.sp -\fBcargo owner [\fIOPTIONS\fP] \-\-add \fILOGIN\fP [\fICRATE\fP]\fP +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-add\fR \fIlogin\fR [\fIcrate\fR] .br -\fBcargo owner [\fIOPTIONS\fP] \-\-remove \fILOGIN\fP [\fICRATE\fP]\fP +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-remove\fR \fIlogin\fR [\fIcrate\fR] .br -\fBcargo owner [\fIOPTIONS\fP] \-\-list [\fICRATE\fP]\fP +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-list\fR [\fIcrate\fR] .SH "DESCRIPTION" -.sp 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! .sp -This command requires you to be authenticated with either the \fB\-\-token\fP option -or using \fBcargo\-login\fP(1). +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). .sp If the crate name is not specified, it will use the package name from the current directory. .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html#cargo\-owner" "the reference" " " -for more +See \fIthe reference\fR for more information about owners and publishing. .SH "OPTIONS" .SS "Owner Options" .sp -\fB\-a\fP, \fB\-\-add\fP \fILOGIN\fP... +\fB\-a\fR, +\fB\-\-add\fR \fIlogin\fR\&... .RS 4 Invite the given user or team as an owner. .RE .sp -\fB\-r\fP, \fB\-\-remove\fP \fILOGIN\fP... +\fB\-r\fR, +\fB\-\-remove\fR \fIlogin\fR\&... .RS 4 Remove the given user or team as an owner. .RE .sp -\fB\-l\fP, \fB\-\-list\fP +\fB\-l\fR, +\fB\-\-list\fR .RS 4 List owners of a crate. .RE .sp -\fB\-\-token\fP \fITOKEN\fP +\fB\-\-token\fR \fItoken\fR .RS 4 API token to use when authenticating. This overrides the token stored in -the credentials file (which is created by \fBcargo\-login\fP(1)). +the credentials file (which is created by \fBcargo\-login\fR(1)). .sp -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " " -environment variables can be +\fICargo config\fR environment variables can be used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment +crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment variable. Tokens for other registries may be specified with environment -variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name of the registry in all capital letters. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -List owners of a package: +\h'-04' 1.\h'+01'List owners of a package: .sp -.if n .RS 4 +.RS 4 .nf cargo owner \-\-list foo .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Invite an owner to a package: +\h'-04' 2.\h'+01'Invite an owner to a package: .sp -.if n .RS 4 +.RS 4 .nf cargo owner \-\-add username foo .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Remove an owner from a package: +\h'-04' 3.\h'+01'Remove an owner from a package: .sp -.if n .RS 4 +.RS 4 .nf cargo owner \-\-remove username foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-login\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index 0a80a18203e..f8c10de6d2c 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -1,270 +1,169 @@ '\" t -.\" Title: cargo-package -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-PACKAGE" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-PACKAGE" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-package \- Assemble the local package into a distributable tarball .SH "SYNOPSIS" -.sp -\fBcargo package [\fIOPTIONS\fP]\fP +\fBcargo package\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This command will create a distributable, compressed \fB.crate\fP file with the +This command will create a distributable, compressed \fB\&.crate\fR file with the source code of the package in the current directory. The resulting file will -be stored in the \fBtarget/package\fP directory. This performs the following +be stored in the \fBtarget/package\fR directory. This performs the following steps: .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Load and check the current workspace, performing some basic checks. -.sp -.RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -Path dependencies are not allowed unless they have a version key. Cargo +\h'-04' 1.\h'+01'Load and check the current workspace, performing some basic checks. +.sp +.RS 4 +\h'-04'\(bu\h'+02'Path dependencies are not allowed unless they have a version key. Cargo will ignore the path key for dependencies in published packages. -\fBdev\-dependencies\fP do not have this restriction. +\fBdev\-dependencies\fR do not have this restriction. .RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Create the compressed \fB.crate\fP file. +\h'-04' 2.\h'+01'Create the compressed \fB\&.crate\fR file. .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The original \fBCargo.toml\fP file is rewritten and normalized. +\h'-04'\(bu\h'+02'The original \fBCargo.toml\fR file is rewritten and normalized. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB[patch]\fP, \fB[replace]\fP, and \fB[workspace]\fP sections are removed from the +\h'-04'\(bu\h'+02'\fB[patch]\fR, \fB[replace]\fR, and \fB[workspace]\fR sections are removed from the manifest. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCargo.lock\fP is automatically included if the package contains an -executable binary or example target. \fBcargo\-install\fP(1) will use the -packaged lock file if the \fB\-\-locked\fP flag is used. +\h'-04'\(bu\h'+02'\fBCargo.lock\fR is automatically included if the package contains an +executable binary or example target. \fBcargo\-install\fR(1) will use the +packaged lock file if the \fB\-\-locked\fR flag is used. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -A \fB.cargo_vcs_info.json\fP file is included that contains information +\h'-04'\(bu\h'+02'A \fB\&.cargo_vcs_info.json\fR file is included that contains information about the current VCS checkout hash if available (not included with -\fB\-\-allow\-dirty\fP). +\fB\-\-allow\-dirty\fR). .RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Extract the \fB.crate\fP file and build it to verify it can build. +\h'-04' 3.\h'+01'Extract the \fB\&.crate\fR file and build it to verify it can build. .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -This will rebuild your package from scratch to ensure that it can be -built from a pristine state. The \fB\-\-no\-verify\fP flag can be used to skip +\h'-04'\(bu\h'+02'This will rebuild your package from scratch to ensure that it can be +built from a pristine state. The \fB\-\-no\-verify\fR flag can be used to skip this step. .RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 4.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 4." 4.2 -.\} -Check that build scripts did not modify any source files. +\h'-04' 4.\h'+01'Check that build scripts did not modify any source files. .RE .sp -The list of files included can be controlled with the \fBinclude\fP and \fBexclude\fP +The list of files included can be controlled with the \fBinclude\fR and \fBexclude\fR fields in the manifest. .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html" "the reference" " " -for more details about +See \fIthe reference\fR for more details about packaging and publishing. .SH "OPTIONS" .SS "Package Options" .sp -\fB\-l\fP, \fB\-\-list\fP +\fB\-l\fR, +\fB\-\-list\fR .RS 4 Print files included in a package without making one. .RE .sp -\fB\-\-no\-verify\fP +\fB\-\-no\-verify\fR .RS 4 -Don\(cqt verify the contents by building them. +Don't verify the contents by building them. .RE .sp -\fB\-\-no\-metadata\fP +\fB\-\-no\-metadata\fR .RS 4 -Ignore warnings about a lack of human\-usable metadata (such as the -description or the license). +Ignore warnings about a lack of human\-usable metadata (such as the description +or the license). .RE .sp -\fB\-\-allow\-dirty\fP +\fB\-\-allow\-dirty\fR .RS 4 Allow working directories with uncommitted VCS changes to be packaged. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Package for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -274,135 +173,100 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Create a compressed \fB.crate\fP file of the current package: +\h'-04' 1.\h'+01'Create a compressed \fB\&.crate\fR file of the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo package .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-pkgid.1 b/src/etc/man/cargo-pkgid.1 index 80b5fbbe15d..128587ec44b 100644 --- a/src/etc/man/cargo-pkgid.1 +++ b/src/etc/man/cargo-pkgid.1 @@ -1,43 +1,17 @@ '\" t -.\" Title: cargo-pkgid -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-PKGID" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-PKGID" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-pkgid \- Print a fully qualified package specification .SH "SYNOPSIS" -.sp -\fBcargo pkgid [\fIOPTIONS\fP] [\fISPEC\fP]\fP +\fBcargo pkgid\fR [\fIoptions\fR] [\fIspec\fR] .SH "DESCRIPTION" -.sp -Given a \fISPEC\fP argument, print out the fully qualified package ID specifier +Given a \fIspec\fR 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 \fISPEC\fP is ambiguous as to which package it refers to in -the dependency graph. If no \fISPEC\fP is given, then the specifier for the local +generate an error if \fIspec\fR is ambiguous as to which package it refers to in +the dependency graph. If no \fIspec\fR is given, then the specifier for the local package is printed. .sp This command requires that a lockfile is available and dependencies have been @@ -45,156 +19,116 @@ fetched. .sp 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 \fISPEC\fP can be one of the +long as it matches only one package. The format of a \fIspec\fR can be one of the following: -.sp -.it 1 an-trap -.nr an-no-space-flag 1 -.nr an-break-flag 1 -.br -.B Table 1. SPEC Query Format + .TS allbox tab(:); lt lt. T{ -.sp SPEC Structure T}:T{ -.sp Example SPEC T} T{ -.sp -\fINAME\fP +\fIname\fR T}:T{ -.sp -\fBbitflags\fP +\fBbitflags\fR T} T{ -.sp -\fINAME\fP\fB:\fP\fIVERSION\fP +\fIname\fR\fB:\fR\fIversion\fR T}:T{ -.sp -\fBbitflags:1.0.4\fP +\fBbitflags:1.0.4\fR T} T{ -.sp -\fIURL\fP +\fIurl\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/cargo" "" "\fP" +\fBhttps://github.com/rust\-lang/cargo\fR T} T{ -.sp -\fIURL\fP\fB#\fP\fIVERSION\fP +\fIurl\fR\fB#\fR\fIversion\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/cargo#0.33.0" "" "\fP" +\fBhttps://github.com/rust\-lang/cargo#0.33.0\fR T} T{ -.sp -\fIURL\fP\fB#\fP\fINAME\fP +\fIurl\fR\fB#\fR\fIname\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/crates.io\-index#bitflags" "" "\fP" +\fBhttps://github.com/rust\-lang/crates.io\-index#bitflags\fR T} T{ -.sp -\fIURL\fP\fB#\fP\fINAME\fP\fB:\fP\fIVERSION\fP +\fIurl\fR\fB#\fR\fIname\fR\fB:\fR\fIversion\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/cargo#crates\-io:0.21.0" "" "\fP" +\fBhttps://github.com/rust\-lang/cargo#crates\-io:0.21.0\fR T} .TE .sp .SH "OPTIONS" .SS "Package Selection" .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 Get the package ID for the given package instead of the current package. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -204,103 +138,74 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Retrieve package specification for \fBfoo\fP package: +\h'-04' 1.\h'+01'Retrieve package specification for \fBfoo\fR package: .sp -.if n .RS 4 +.RS 4 .nf cargo pkgid foo .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Retrieve package specification for version 1.0.0 of \fBfoo\fP: +\h'-04' 2.\h'+01'Retrieve package specification for version 1.0.0 of \fBfoo\fR: .sp -.if n .RS 4 +.RS 4 .nf cargo pkgid foo:1.0.0 .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Retrieve package specification for \fBfoo\fP from crates.io: +\h'-04' 3.\h'+01'Retrieve package specification for \fBfoo\fR from crates.io: .sp -.if n .RS 4 +.RS 4 .nf cargo pkgid https://github.com/rust\-lang/crates.io\-index#foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-generate\-lockfile\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index 716127628cb..1bac92f5ef2 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -1,220 +1,157 @@ '\" t -.\" Title: cargo-publish -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-PUBLISH" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-PUBLISH" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-publish \- Upload a package to the registry .SH "SYNOPSIS" -.sp -\fBcargo publish [\fIOPTIONS\fP]\fP +\fBcargo publish\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This command will create a distributable, compressed \fB.crate\fP file with the +This command will create a distributable, compressed \fB\&.crate\fR file with the source code of the package in the current directory and upload it to a -registry. The default registry is \c -.URL "https://crates.io" "" "." -This performs the +registry. The default registry is \&. This performs the following steps: .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Performs a few checks, including: +\h'-04' 1.\h'+01'Performs a few checks, including: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -Checks the \fBpackage.publish\fP key in the manifest for restrictions on which -registries you are allowed to publish to. +\h'-04'\(bu\h'+02'Checks the \fBpackage.publish\fR key in the manifest for restrictions on +which registries you are allowed to publish to. .RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Create a \fB.crate\fP file by following the steps in \fBcargo\-package\fP(1). +\h'-04' 2.\h'+01'Create a \fB\&.crate\fR file by following the steps in \fBcargo\-package\fR(1). .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Upload the crate to the registry. Note that the server will perform +\h'-04' 3.\h'+01'Upload the crate to the registry. Note that the server will perform additional checks on the crate. .RE .sp -This command requires you to be authenticated with either the \fB\-\-token\fP option -or using \fBcargo\-login\fP(1). +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html" "the reference" " " -for more details about +See \fIthe reference\fR for more details about packaging and publishing. .SH "OPTIONS" .SS "Publish Options" .sp -\fB\-\-dry\-run\fP +\fB\-\-dry\-run\fR .RS 4 Perform all checks without uploading. .RE .sp -\fB\-\-token\fP \fITOKEN\fP +\fB\-\-token\fR \fItoken\fR .RS 4 API token to use when authenticating. This overrides the token stored in -the credentials file (which is created by \fBcargo\-login\fP(1)). +the credentials file (which is created by \fBcargo\-login\fR(1)). .sp -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " " -environment variables can be +\fICargo config\fR environment variables can be used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment +crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment variable. Tokens for other registries may be specified with environment -variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name of the registry in all capital letters. .RE .sp -\fB\-\-no\-verify\fP +\fB\-\-no\-verify\fR .RS 4 -Don\(cqt verify the contents by building them. +Don't verify the contents by building them. .RE .sp -\fB\-\-allow\-dirty\fP +\fB\-\-allow\-dirty\fR .RS 4 Allow working directories with uncommitted VCS changes to be packaged. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Publish for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -224,135 +161,100 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Publish the current package: +\h'-04' 1.\h'+01'Publish the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo publish .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-package\fP(1), \fBcargo\-login\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-package\fR(1), \fBcargo\-login\fR(1) diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 16c1da54a04..4ba8a36bda6 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -1,292 +1,200 @@ '\" t -.\" Title: cargo-run -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-04-21 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-RUN" "1" "2020-04-21" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-RUN" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-run \- Run the current package .SH "SYNOPSIS" -.sp -\fBcargo run [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +\fBcargo run\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] .SH "DESCRIPTION" -.sp Run a binary or example of the local package. .sp -All the arguments following the two dashes (\fB\-\-\fP) are passed to the binary to -run. If you\(cqre passing arguments to both Cargo and the binary, the ones after -\fB\-\-\fP go to the binary, the ones before go to Cargo. +All the arguments following the two dashes (\fB\-\-\fR) are passed to the binary to +run. If you're passing arguments to both Cargo and the binary, the ones after +\fB\-\-\fR go to the binary, the ones before go to Cargo. .SH "OPTIONS" .SS "Package Selection" -.sp -By default, the package in the current working directory is selected. The \fB\-p\fP +By default, the package in the current working directory is selected. The \fB\-p\fR flag can be used to choose a different package in a workspace. .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 -The package to run. See \fBcargo\-pkgid\fP(1) for -the SPEC format. +The package to run. See \fBcargo\-pkgid\fR(1) for the SPEC +format. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo run\fP will run the binary +When no target selection options are given, \fBcargo run\fR will run the binary target. If there are multiple binary targets, you must pass a target flag to -choose one. Or, the \fBdefault\-run\fP field may be specified in the \fB[package]\fP -section of \fBCargo.toml\fP to choose the name of the binary to run by default. +choose one. Or, the \fBdefault\-run\fR field may be specified in the \fB[package]\fR +section of \fBCargo.toml\fR to choose the name of the binary to run by default. .sp -\fB\-\-bin\fP \fINAME\fP +\fB\-\-bin\fR \fIname\fR .RS 4 Run the specified binary. .RE .sp -\fB\-\-example\fP \fINAME\fP +\fB\-\-example\fR \fIname\fR .RS 4 Run the specified example. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Run for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Run optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Run optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -296,146 +204,110 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Build the local package and run its main target (assuming only one binary): +\h'-04' 1.\h'+01'Build the local package and run its main target (assuming only one binary): .sp -.if n .RS 4 +.RS 4 .nf cargo run .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Run an example with extra arguments: +\h'-04' 2.\h'+01'Run an example with extra arguments: .sp -.if n .RS 4 +.RS 4 .nf cargo run \-\-example exname \-\- \-\-exoption exarg1 exarg2 .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index a8b6f14eaeb..6d42059db58 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -1,363 +1,267 @@ '\" t -.\" Title: cargo-rustc -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-RUSTC" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-RUSTC" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-rustc \- Compile the current package, and pass extra options to the compiler .SH "SYNOPSIS" -.sp -\fBcargo rustc [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +\fBcargo rustc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] .SH "DESCRIPTION" -.sp -The specified target for the current package (or package specified by \fB\-p\fP if +The specified target for the current package (or package specified by \fB\-p\fR if provided) will be compiled along with all of its dependencies. The specified -\fIARGS\fP will all be passed to the final compiler invocation, not any of the +\fIargs\fR 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 \fB\-L\fP, \fB\-\-extern\fP, and \fB\-\-crate\-type\fP, and the specified -\fIARGS\fP will simply be added to the compiler invocation. +arguments such as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified +\fIargs\fR will simply be added to the compiler invocation. .sp -See \c -.URL "https://doc.rust\-lang.org/rustc/index.html" "" " " -for documentation on rustc +See for documentation on rustc flags. .sp This command requires that only one target is being compiled when additional arguments are provided. If more than one target is available for the current -package the filters of \fB\-\-lib\fP, \fB\-\-bin\fP, etc, must be used to select which +package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which target is compiled. -To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fP -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable" " " -or the -\fBbuild.rustflags\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fR +\fIenvironment variable\fR or the +\fBbuild.rustflags\fR \fIconfig value\fR \&. .SH "OPTIONS" .SS "Package Selection" -.sp -By default, the package in the current working directory is selected. The \fB\-p\fP +By default, the package in the current working directory is selected. The \fB\-p\fR flag can be used to choose a different package in a workspace. .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 -The package to build. See \fBcargo\-pkgid\fP(1) for -the SPEC format. +The package to build. See \fBcargo\-pkgid\fR(1) for the SPEC +format. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo rustc\fP will build all +When no target selection options are given, \fBcargo rustc\fR will build all binary and library targets of the selected package. .sp -Passing target selection flags will build only the -specified targets. +Passing target selection flags will build only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Build the package\(cqs library. +Build the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Build the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Build all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Build the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Build all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Build the specified integration test. This flag may be specified multiple -times. +Build the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Build all targets in test mode that have the \fBtest = true\fP manifest +Build all targets in test mode that have the \fBtest = true\fR 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 \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Build the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Build all targets in benchmark mode that have the \fBbench = true\fP +Build all targets in benchmark mode that have the \fBbench = true\fR 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 \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Build for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Build optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Build optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -367,147 +271,111 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Check if your package (not including dependencies) uses unsafe code: +\h'-04' 1.\h'+01'Check if your package (not including dependencies) uses unsafe code: .sp -.if n .RS 4 +.RS 4 .nf cargo rustc \-\-lib \-\- \-D unsafe\-code .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Try an experimental flag on the nightly compiler, such as this which prints +\h'-04' 2.\h'+01'Try an experimental flag on the nightly compiler, such as this which prints the size of every type: .sp -.if n .RS 4 +.RS 4 .nf cargo rustc \-\-lib \-\- \-Z print\-type\-sizes .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1), \fBrustc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1), \fBrustc\fR(1) diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 88271e1462a..86432194129 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -1,373 +1,276 @@ '\" t -.\" Title: cargo-rustdoc -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-RUSTDOC" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-RUSTDOC" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" -cargo\-rustdoc \- Build a package\(aqs documentation, using specified custom flags +cargo\-rustdoc \- Build a package's documentation, using specified custom flags .SH "SYNOPSIS" -.sp -\fBcargo rustdoc [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +\fBcargo rustdoc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] .SH "DESCRIPTION" -.sp -The specified target for the current package (or package specified by \fB\-p\fP if -provided) will be documented with the specified \fIARGS\fP being passed to the +The specified target for the current package (or package specified by \fB\-p\fR if +provided) will be documented with the specified \fIargs\fR 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 \fB\-L\fP, \fB\-\-extern\fP, and \fB\-\-crate\-type\fP, and the specified \fIARGS\fP will simply +as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified \fIargs\fR will simply be added to the rustdoc invocation. .sp -See \c -.URL "https://doc.rust\-lang.org/rustdoc/index.html" "" " " -for documentation on rustdoc +See for documentation on rustdoc flags. .sp This command requires that only one target is being compiled when additional arguments are provided. If more than one target is available for the current -package the filters of \fB\-\-lib\fP, \fB\-\-bin\fP, etc, must be used to select which +package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which target is compiled. +.sp To pass flags to all rustdoc processes spawned by Cargo, use the -\fBRUSTDOCFLAGS\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable" -or the \fBbuild.rustdocflags\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +\fBRUSTDOCFLAGS\fR \fIenvironment variable\fR +or the \fBbuild.rustdocflags\fR \fIconfig value\fR \&. .SH "OPTIONS" .SS "Documentation Options" .sp -\fB\-\-open\fP +\fB\-\-open\fR .RS 4 Open the docs in a browser after building them. This will use your default -browser unless you define another one in the \fBBROWSER\fP environment -variable. +browser unless you define another one in the \fBBROWSER\fR environment variable. .RE .SS "Package Selection" -.sp -By default, the package in the current working directory is selected. The \fB\-p\fP +By default, the package in the current working directory is selected. The \fB\-p\fR flag can be used to choose a different package in a workspace. .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 -The package to document. See \fBcargo\-pkgid\fP(1) for -the SPEC format. +The package to document. See \fBcargo\-pkgid\fR(1) for the SPEC +format. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo rustdoc\fP will document all +When no target selection options are given, \fBcargo rustdoc\fR 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 -\fBrequired\-features\fP that are missing. +\fBrequired\-features\fR that are missing. .sp -Passing target selection flags will document only the -specified targets. +Passing target selection flags will document only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Document the package\(cqs library. +Document the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Document the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Document all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Document the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Document all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Document the specified integration test. This flag may be specified multiple -times. +Document the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Document all targets in test mode that have the \fBtest = true\fP manifest +Document all targets in test mode that have the \fBtest = true\fR 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 \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Document the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Document all targets in benchmark mode that have the \fBbench = true\fP +Document all targets in benchmark mode that have the \fBbench = true\fR 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 \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Document all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Document all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Document for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Document optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Document optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -377,129 +280,100 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Build documentation with custom CSS included from a given file: +\h'-04' 1.\h'+01'Build documentation with custom CSS included from a given file: .sp -.if n .RS 4 +.RS 4 .nf cargo rustdoc \-\-lib \-\- \-\-extend\-css extra.css .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-doc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-doc\fR(1), \fBrustdoc\fR(1) diff --git a/src/etc/man/cargo-search.1 b/src/etc/man/cargo-search.1 index 3999d4b0ff0..350b2dbb8aa 100644 --- a/src/etc/man/cargo-search.1 +++ b/src/etc/man/cargo-search.1 @@ -1,177 +1,116 @@ '\" t -.\" Title: cargo-search -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-SEARCH" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-SEARCH" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-search \- Search packages in crates.io .SH "SYNOPSIS" -.sp -\fBcargo search [\fIOPTIONS\fP] [\fIQUERY\fP...]\fP +\fBcargo search\fR [\fIoptions\fR] [\fIquery\fR\&...] .SH "DESCRIPTION" -.sp -This performs a textual search for crates on \c -.URL "https://crates.io" "" "." -The matching +This performs a textual search for crates on \&. The matching crates will be displayed along with their description in TOML format suitable -for copying into a \fBCargo.toml\fP manifest. +for copying into a \fBCargo.toml\fR manifest. .SH "OPTIONS" .SS "Search Options" .sp -\fB\-\-limit\fP \fILIMIT\fP +\fB\-\-limit\fR \fIlimit\fR .RS 4 Limit the number of results (default: 10, max: 100). .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Search for a package from crates.io: +\h'-04' 1.\h'+01'Search for a package from crates.io: .sp -.if n .RS 4 +.RS 4 .nf cargo search serde .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-install\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-install\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index bbcc99186ca..c21747ee4c7 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -1,526 +1,380 @@ '\" t -.\" Title: cargo-test -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-07-28 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-TEST" "1" "2020-07-28" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-TEST" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-test \- Execute unit and integration tests of a package .SH "SYNOPSIS" -.sp -\fBcargo test [\fIOPTIONS\fP] [TESTNAME] [\-\- \fITEST\-OPTIONS\fP]\fP +\fBcargo test\fR [\fIoptions\fR] [\fItestname\fR] [\fB\-\-\fR \fItest\-options\fR] .SH "DESCRIPTION" -.sp Compile and execute unit and integration tests. .sp -The test filtering argument \fBTESTNAME\fP and all the arguments following the two -dashes (\fB\-\-\fP) are passed to the test binaries and thus to \fIlibtest\fP (rustc\(cqs -built in unit\-test and micro\-benchmarking framework). If you\(cqre passing -arguments to both Cargo and the binary, the ones after \fB\-\-\fP go to the binary, -the ones before go to Cargo. For details about libtest\(cqs arguments see the -output of \fBcargo test \-\- \-\-help\fP. +The test filtering argument \fBTESTNAME\fR and all the arguments following the two +dashes (\fB\-\-\fR) are passed to the test binaries and thus to \fIlibtest\fR (rustc's +built in unit\-test and micro\-benchmarking framework). If you're passing +arguments to both Cargo and the binary, the ones after \fB\-\-\fR go to the binary, +the ones before go to Cargo. For details about libtest's arguments see the +output of \fBcargo test \-\- \-\-help\fR\&. .sp -As an example, this will filter for tests with \fBfoo\fP in their name and run them +As an example, this will filter for tests with \fBfoo\fR in their name and run them on 3 threads in parallel: .sp -.if n .RS 4 +.RS 4 .nf cargo test foo \-\- \-\-test\-threads 3 .fi -.if n .RE +.RE .sp -Tests are built with the \fB\-\-test\fP option to \fBrustc\fP which creates an -executable with a \fBmain\fP function that automatically runs all functions -annotated with the \fB#[test]\fP attribute in multiple threads. \fB#[bench]\fP +Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an +executable with a \fBmain\fR function that automatically runs all functions +annotated with the \fB#[test]\fR attribute in multiple threads. \fB#[bench]\fR annotated functions will also be run with one iteration to verify that they are functional. .sp -The libtest harness may be disabled by setting \fBharness = false\fP in the target -manifest settings, in which case your code will need to provide its own \fBmain\fP +The libtest harness may be disabled by setting \fBharness = false\fR in the target +manifest settings, in which case your code will need to provide its own \fBmain\fR function to handle running tests. .sp -Documentation tests are also run by default, which is handled by \fBrustdoc\fP. It +Documentation tests are also run by default, which is handled by \fBrustdoc\fR\&. It extracts code samples from documentation comments and executes them. See the -.URL "https://doc.rust\-lang.org/rustdoc/" "rustdoc book" " " -for more information on +\fIrustdoc book\fR for more information on writing doc tests. .SH "OPTIONS" .SS "Test Options" .sp -\fB\-\-no\-run\fP +\fB\-\-no\-run\fR .RS 4 -Compile, but don\(cqt run tests. +Compile, but don't run tests. .RE .sp -\fB\-\-no\-fail\-fast\fP +\fB\-\-no\-fail\-fast\fR .RS 4 Run all tests regardless of failure. Without this flag, Cargo will exit -after the first executable fails. The Rust test harness will run all -tests within the executable to completion, this flag only applies to -the executable as a whole. +after the first executable fails. The Rust test harness will run all tests +within the executable to completion, this flag only applies to the executable +as a whole. .RE .SS "Package Selection" -.sp 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 -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Test only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Test only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Test all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo test\fP will build the +When no target selection options are given, \fBcargo test\fR will build the following targets of the selected packages: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -lib — used to link with binaries, examples, integration tests, and doc tests +\h'-04'\(bu\h'+02'lib \[em] used to link with binaries, examples, integration tests, and doc tests .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -bins (only if integration tests are built and required features are +\h'-04'\(bu\h'+02'bins (only if integration tests are built and required features are available) .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -examples — to ensure they compile +\h'-04'\(bu\h'+02'examples \[em] to ensure they compile .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -lib as a unit test +\h'-04'\(bu\h'+02'lib as a unit test .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -bins as unit tests +\h'-04'\(bu\h'+02'bins as unit tests .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -integration tests +\h'-04'\(bu\h'+02'integration tests .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -doc tests for the lib target +\h'-04'\(bu\h'+02'doc tests for the lib target .RE .sp -The default behavior can be changed by setting the \fBtest\fP flag for the target -in the manifest settings. Setting examples to \fBtest = true\fP will build and run -the example as a test. Setting targets to \fBtest = false\fP will stop them from +The default behavior can be changed by setting the \fBtest\fR flag for the target +in the manifest settings. Setting examples to \fBtest = true\fR will build and run +the example as a test. Setting targets to \fBtest = false\fR will stop them from being tested by default. Target selection options that take a target by name -ignore the \fBtest\fP flag and will always test the given target. +ignore the \fBtest\fR flag and will always test the given target. .sp -Doc tests for libraries may be disabled by setting \fBdoctest = false\fP for the +Doc tests for libraries may be disabled by setting \fBdoctest = false\fR for the library in the manifest. .sp 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 \fBCARGO_BIN_EXE_\fP -\c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates" "environment variable" +and test its behavior. The \fBCARGO_bin_EXE_\fR +\fIenvironment variable\fR is set when the integration test is built so that it can use the -.URL "https://doc.rust\-lang.org/std/macro.env.html" "\fBenv\fP macro" " " -to locate the +\fI\f(BIenv\fI macro\fR to locate the executable. .sp -Passing target selection flags will test only the -specified targets. +Passing target selection flags will test only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Test the package\(cqs library. +Test the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Test the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Test all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Test the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Test all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Test the specified integration test. This flag may be specified multiple -times. +Test the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Test all targets in test mode that have the \fBtest = true\fP manifest +Test all targets in test mode that have the \fBtest = true\fR 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 \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Test the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Test all targets in benchmark mode that have the \fBbench = true\fP +Test all targets in benchmark mode that have the \fBbench = true\fR 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 \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Test all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Test all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .sp -\fB\-\-doc\fP +\fB\-\-doc\fR .RS 4 -Test only the library\(cqs documentation. This cannot be mixed with other +Test only the library's documentation. This cannot be mixed with other target options. .RE .SS "Feature Selection" -.sp 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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Test for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR for a list of supported targets. .sp -This may also be specified with the \fBbuild.target\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Test optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Test optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the -\fBbuild.target\-dir\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults -to \fBtarget\fP in the root of the workspace. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" -.sp 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 -\fB\-\-nocapture\fP to the test binaries: +\fB\-\-nocapture\fR to the test binaries: .sp -.if n .RS 4 +.RS 4 .nf cargo test \-\- \-\-nocapture .fi -.if n .RE +.RE .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBhuman\fP (default): Display in a human\-readable text format. +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\fP: Emit JSON messages to stdout. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -530,181 +384,137 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" -.sp -The \fB\-\-jobs\fP argument affects the building of the test executable but does not +The \fB\-\-jobs\fR 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 includes an option to control the number of threads used: .sp -.if n .RS 4 +.RS 4 .nf cargo test \-j 2 \-\- \-\-test\-threads=2 .fi -.if n .RE +.RE .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SH "PROFILES" -.sp Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR for more +details. .sp Profile selection depends on the target and crate being built. By default the -\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the -\fBrelease\fP or \fBbench\fP profiles are used. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .sp -Unit tests are separate executable artifacts which use the \fBtest\fP/\fBbench\fP -profiles. Example targets are built the same as with \fBcargo build\fP (using the -\fBdev\fP/\fBrelease\fP profiles) unless you are building them with the test harness -(by setting \fBtest = true\fP in the manifest or using the \fB\-\-example\fP flag) in -which case they use the \fBtest\fP/\fBbench\fP profiles. Library targets are built -with the \fBdev\fP/\fBrelease\fP profiles when linked to an integration test, binary, +Unit tests are separate executable artifacts which use the \fBtest\fR/\fBbench\fR +profiles. Example targets are built the same as with \fBcargo build\fR (using the +\fBdev\fR/\fBrelease\fR profiles) unless you are building them with the test harness +(by setting \fBtest = true\fR in the manifest or using the \fB\-\-example\fR flag) in +which case they use the \fBtest\fR/\fBbench\fR profiles. Library targets are built +with the \fBdev\fR/\fBrelease\fR profiles when linked to an integration test, binary, or doctest. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Execute all the unit and integration tests of the current package: +\h'-04' 1.\h'+01'Execute all the unit and integration tests of the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo test .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Run only tests whose names match against a filter string: +\h'-04' 2.\h'+01'Run only tests whose names match against a filter string: .sp -.if n .RS 4 +.RS 4 .nf cargo test name_filter .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Run only a specific test within a specific integration test: +\h'-04' 3.\h'+01'Run only a specific test within a specific integration test: .sp -.if n .RS 4 +.RS 4 .nf cargo test \-\-test int_test_name \-\- modname::test_name .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-bench\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-bench\fR(1) diff --git a/src/etc/man/cargo-tree.1 b/src/etc/man/cargo-tree.1 index 70179add29d..73f27c6eee0 100644 --- a/src/etc/man/cargo-tree.1 +++ b/src/etc/man/cargo-tree.1 @@ -1,43 +1,17 @@ '\" t -.\" Title: cargo-tree -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-TREE" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-TREE" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-tree \- Display a tree visualization of a dependency graph .SH "SYNOPSIS" -.sp -\fBcargo tree [\fIOPTIONS\fP]\fP +\fBcargo tree\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp This command will display a tree of dependencies to the terminal. An example of a simple project that depends on the "rand" package: .sp -.if n .RS 4 +.RS 4 .nf myproject v0.1.0 (/myproject) `\-\- rand v0.7.3 @@ -53,17 +27,17 @@ myproject v0.1.0 (/myproject) [build\-dependencies] `\-\- cc v1.0.50 .fi -.if n .RE +.RE .sp -Packages marked with \fB(*)\fP have been "de\-duplicated". The dependencies for the +Packages marked with \fB(*)\fR have been "de\-duplicated". The dependencies for the package have already been shown elswhere in the graph, and so are not -repeated. Use the \fB\-\-no\-dedupe\fP option to repeat the duplicates. +repeated. Use the \fB\-\-no\-dedupe\fR option to repeat the duplicates. .sp -The \fB\-e\fP flag can be used to select the dependency kinds to display. The +The \fB\-e\fR 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, \fBcargo tree \-e features\fP: +each dependency. For example, \fBcargo tree \-e features\fR: .sp -.if n .RS 4 +.RS 4 .nf myproject v0.1.0 (/myproject) `\-\- log feature "serde" @@ -72,41 +46,43 @@ myproject v0.1.0 (/myproject) `\-\- cfg\-if feature "default" `\-\- cfg\-if v0.1.10 .fi -.if n .RE +.RE .sp -In this tree, \fBmyproject\fP depends on \fBlog\fP with the \fBserde\fP feature. \fBlog\fP in -turn depends on \fBcfg\-if\fP with "default" features. When using \fB\-e features\fP it -can be helpful to use \fB\-i\fP flag to show how the features flow into a package. +In this tree, \fBmyproject\fR depends on \fBlog\fR with the \fBserde\fR feature. \fBlog\fR in +turn depends on \fBcfg\-if\fR with "default" features. When using \fB\-e features\fR it +can be helpful to use \fB\-i\fR flag to show how the features flow into a package. See the examples below for more detail. .SH "OPTIONS" .SS "Tree Options" .sp -\fB\-i\fP \fISPEC\fP, \fB\-\-invert\fP \fISPEC\fP +\fB\-i\fR \fIspec\fR, +\fB\-\-invert\fR \fIspec\fR .RS 4 Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package. .sp -Note that in a workspace, by default it will only display the package\(cqs +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 \fB\-\-workspace\fP flag can be used to extend it so that it will -show the package\(cqs reverse dependencies across the entire workspace. The \fB\-p\fP -flag can be used to display the package\(cqs reverse dependencies only with the -subtree of the package given to \fB\-p\fP. +directory. The \fB\-\-workspace\fR flag can be used to extend it so that it will +show the package's reverse dependencies across the entire workspace. The \fB\-p\fR +flag can be used to display the package's reverse dependencies only with the +subtree of the package given to \fB\-p\fR\&. .RE .sp -\fB\-\-no\-dedupe\fP +\fB\-\-no\-dedupe\fR .RS 4 -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 \fB(*)\fP to indicate it has -already been shown. This flag will cause those duplicates to be repeated. +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 \fB(*)\fR to indicate it has already been shown. +This flag will cause those duplicates to be repeated. .RE .sp -\fB\-d\fP, \fB\-\-duplicates\fP +\fB\-d\fR, +\fB\-\-duplicates\fR .RS 4 -Show only dependencies which come in multiple versions (implies -\fB\-\-invert\fP). When used with the \fB\-p\fP flag, only shows duplicates within -the subtree of the given package. +Show only dependencies which come in multiple versions (implies \fB\-\-invert\fR). +When used with the \fB\-p\fR flag, only shows duplicates within the subtree of the +given package. .sp 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 @@ -115,120 +91,64 @@ duplicate with the older version can be updated to the newer version so that only one instance is built. .RE .sp -\fB\-e\fP \fIKINDS\fP, \fB\-\-edges\fP \fIKINDS\fP +\fB\-e\fR \fIkinds\fR, +\fB\-\-edges\fR \fIkinds\fR .RS 4 The dependency kinds to display. Takes a comma separated list of values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBall\fP — Show all edge kinds. +\h'-04'\(bu\h'+02'\fBall\fR \[em] Show all edge kinds. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnormal\fP — Show normal dependencies. +\h'-04'\(bu\h'+02'\fBnormal\fR \[em] Show normal dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBbuild\fP — Show build dependencies. +\h'-04'\(bu\h'+02'\fBbuild\fR \[em] Show build dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBdev\fP — Show development dependencies. +\h'-04'\(bu\h'+02'\fBdev\fR \[em] Show development dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBfeatures\fP — Show features enabled by each dependency. If this is -the only kind given, then it will automatically include the other -dependency kinds. +\h'-04'\(bu\h'+02'\fBfeatures\fR \[em] Show features enabled by each dependency. If this is the only +kind given, then it will automatically include the other dependency kinds. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBno\-normal\fP — Do not include normal dependencies. +\h'-04'\(bu\h'+02'\fBno\-normal\fR \[em] Do not include normal dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBno\-build\fP — Do not include build dependencies. +\h'-04'\(bu\h'+02'\fBno\-build\fR \[em] Do not include build dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBno\-dev\fP — Do not include development dependencies. +\h'-04'\(bu\h'+02'\fBno\-dev\fR \[em] Do not include development dependencies. .RE .sp -The \fBno\-\fP prefixed options cannot be mixed with the other dependency kinds. +The \fBno\-\fR prefixed options cannot be mixed with the other dependency kinds. .sp -The default is \fBnormal,build,dev\fP. +The default is \fBnormal,build,dev\fR\&. .RE .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 -Filter dependencies matching the given target\-triple. -The default is the host platform. Use the value \fBall\fP to include \fBall\fP -targets. +Filter dependencies matching the given target\-triple. The default is the host +platform. Use the value \fBall\fR to include \fIall\fR targets. .RE .SS "Tree Formatting Options" .sp -\fB\-\-charset\fP \fICHARSET\fP +\fB\-\-charset\fR \fIcharset\fR .RS 4 Chooses the character set to use for the tree. Valid values are "utf8" or "ascii". Default is "utf8". .RE .sp -\fB\-f\fP \fIFORMAT\fP, \fB\-\-format\fP \fIFORMAT\fP +\fB\-f\fR \fIformat\fR, +\fB\-\-format\fR \fIformat\fR .RS 4 Set the format string for each package. The default is "{p}". .sp @@ -236,368 +156,257 @@ This is an arbitrary string which will be used to display each package. The foll strings will be replaced with the corresponding value: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{p}\fP — The package name. +\h'-04'\(bu\h'+02'\fB{p}\fR \[em] The package name. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{l}\fP — The package license. +\h'-04'\(bu\h'+02'\fB{l}\fR \[em] The package license. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{r}\fP — The package repository URL. +\h'-04'\(bu\h'+02'\fB{r}\fR \[em] The package repository URL. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{f}\fP — Comma\-separated list of package features that are enabled. +\h'-04'\(bu\h'+02'\fB{f}\fR \[em] Comma\-separated list of package features that are enabled. .RE .RE .sp -\fB\-\-prefix\fP \fIPREFIX\fP +\fB\-\-prefix\fR \fIprefix\fR .RS 4 -Sets how each line is displayed. The \fIPREFIX\fP value can be one of: +Sets how each line is displayed. The \fIprefix\fR value can be one of: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBindent\fP (default) — Shows each line indented as a tree. +\h'-04'\(bu\h'+02'\fBindent\fR (default) \[em] Shows each line indented as a tree. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBdepth\fP — Show as a list, with the numeric depth printed before each entry. +\h'-04'\(bu\h'+02'\fBdepth\fR \[em] Show as a list, with the numeric depth printed before each entry. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnone\fP — Show as a flat list. +\h'-04'\(bu\h'+02'\fBnone\fR \[em] Show as a flat list. .RE .RE .SS "Package Selection" -.sp 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 -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Display only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Display only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Display all members in the workspace. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE -.SS "Feature Selection" .sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +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. +.sp +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 \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. +.RE +.SS "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 -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .RS 4 Space or comma separated list of features to activate. These features only -apply to the current directory\(cqs package. Features of direct dependencies -may be enabled with \fB/\fP syntax. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... -.RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. -.RE -.sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-Z\fR \fIflag\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is -up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from -attempting to access the network to determine if it is out\-of\-date. -.sp -These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network -access. -.RE -.sp -\fB\-\-offline\fP -.RS 4 -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. -.sp -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 \fBcargo\-fetch\fP(1) command to download dependencies before going -offline. -.sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Display the tree for the package in the current directory: +\h'-04' 1.\h'+01'Display the tree for the package in the current directory: .sp -.if n .RS 4 +.RS 4 .nf cargo tree .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Display all the packages that depend on the \fBsyn\fP package: +\h'-04' 2.\h'+01'Display all the packages that depend on the \fBsyn\fR package: .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-i syn .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Show the features enabled on each package: +\h'-04' 3.\h'+01'Show the features enabled on each package: .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-\-format "{p} {f}" .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 4.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 4." 4.2 -.\} -Show all packages that are built multiple times. This can happen if multiple +\h'-04' 4.\h'+01'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). .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-d .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 5.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 5." 4.2 -.\} -Explain why features are enabled for the \fBsyn\fP package: +\h'-04' 5.\h'+01'Explain why features are enabled for the \fBsyn\fR package: .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-e features \-i syn .fi -.if n .RE +.RE .sp -The \fB\-e features\fP flag is used to show features. The \fB\-i\fP flag is used to -invert the graph so that it displays the packages that depend on \fBsyn\fP. An +The \fB\-e features\fR flag is used to show features. The \fB\-i\fR flag is used to +invert the graph so that it displays the packages that depend on \fBsyn\fR\&. An example of what this would display: .sp -.if n .RS 4 +.RS 4 .nf syn v1.0.17 |\-\- syn feature "clone\-impls" @@ -621,18 +430,17 @@ syn v1.0.17 |\-\- syn feature "printing" (*) `\-\- syn feature "proc\-macro" (*) .fi -.if n .RE +.RE .sp -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 -\fBrustversion\fP crate which is included from \fBmyproject\fP (with the default -features), and \fBmyproject\fP is the package selected on the command\-line. All -of the other \fBsyn\fP features are added by the "default" feature ("quote" is +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 +\fBrustversion\fR crate which is included from \fBmyproject\fR (with the default +features), and \fBmyproject\fR is the package selected on the command\-line. All +of the other \fBsyn\fR features are added by the "default" feature ("quote" is added by "printing" and "proc\-macro", both of which are default features). .sp -If you\(cqre having difficulty cross\-referencing the de\-duplicated \fB(*)\fP entries, -try with the \fB\-\-no\-dedupe\fP flag to get the full output. +If you're having difficulty cross\-referencing the de\-duplicated \fB(*)\fR +entries, try with the \fB\-\-no\-dedupe\fR flag to get the full output. .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-uninstall.1 b/src/etc/man/cargo-uninstall.1 index d78a5a53a36..d6743dcec18 100644 --- a/src/etc/man/cargo-uninstall.1 +++ b/src/etc/man/cargo-uninstall.1 @@ -1,233 +1,139 @@ '\" t -.\" Title: cargo-uninstall -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-UNINSTALL" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-UNINSTALL" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-uninstall \- Remove a Rust binary .SH "SYNOPSIS" -.sp -\fBcargo uninstall [\fIOPTIONS\fP] [\fISPEC\fP...]\fP +\fBcargo uninstall\fR [\fIoptions\fR] [\fIspec\fR\&...] .SH "DESCRIPTION" -.sp -This command removes a package installed with \fBcargo\-install\fP(1). The \fISPEC\fP +This command removes a package installed with \fBcargo\-install\fR(1). The \fIspec\fR argument is a package ID specification of the package to remove (see -\fBcargo\-pkgid\fP(1)). +\fBcargo\-pkgid\fR(1)). .sp -By default all binaries are removed for a crate but the \fB\-\-bin\fP and -\fB\-\-example\fP flags can be used to only remove particular binaries. +By default all binaries are removed for a crate but the \fB\-\-bin\fR and +\fB\-\-example\fR flags can be used to only remove particular binaries. .sp The installation root is determined, in order of precedence: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB\-\-root\fP option +\h'-04'\(bu\h'+02'\fB\-\-root\fR option .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_INSTALL_ROOT\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBinstall.root\fP Cargo \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "" +\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_HOME\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR environment variable .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB$HOME/.cargo\fP +\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR .RE .SH "OPTIONS" .SS "Install Options" .sp -\fB\-p\fP, \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR, +\fB\-\-package\fR \fIspec\fR\&... .RS 4 Package to uninstall. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 -Only uninstall the binary \fINAME\fP. +Only uninstall the binary \fIname\fR\&. .RE .sp -\fB\-\-root\fP \fIDIR\fP +\fB\-\-root\fR \fIdir\fR .RS 4 Directory to uninstall packages from. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Uninstall a previously installed package. +\h'-04' 1.\h'+01'Uninstall a previously installed package. .sp -.if n .RS 4 +.RS 4 .nf cargo uninstall ripgrep .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-install\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-install\fR(1) diff --git a/src/etc/man/cargo-update.1 b/src/etc/man/cargo-update.1 index 2b321002ed4..0cf6cf2b0f8 100644 --- a/src/etc/man/cargo-update.1 +++ b/src/etc/man/cargo-update.1 @@ -1,153 +1,110 @@ '\" t -.\" Title: cargo-update -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-UPDATE" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-UPDATE" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-update \- Update dependencies as recorded in the local lock file .SH "SYNOPSIS" -.sp -\fBcargo update [\fIOPTIONS\fP]\fP +\fBcargo update\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This command will update dependencies in the \fBCargo.lock\fP file to the latest -version. It requires that the \fBCargo.lock\fP file already exists as generated -by commands such as \fBcargo\-build\fP(1) or \fBcargo\-generate\-lockfile\fP(1). +This command will update dependencies in the \fBCargo.lock\fR file to the latest +version. It requires that the \fBCargo.lock\fR file already exists as generated +by commands such as \fBcargo\-build\fR(1) or \fBcargo\-generate\-lockfile\fR(1). .SH "OPTIONS" .SS "Update Options" .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 Update only the specified packages. This flag may be specified -multiple times. See \fBcargo\-pkgid\fP(1) for the SPEC format. +multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format. .sp -If packages are specified with the \fB\-p\fP flag, then a conservative update of +If packages are specified with the \fB\-p\fR 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. .sp -If \fB\-p\fP is not specified, all dependencies are updated. +If \fB\-p\fR is not specified, all dependencies are updated. .RE .sp -\fB\-\-aggressive\fP +\fB\-\-aggressive\fR .RS 4 -When used with \fB\-p\fP, dependencies of \fISPEC\fP are forced to update as well. -Cannot be used with \fB\-\-precise\fP. +When used with \fB\-p\fR, dependencies of \fIspec\fR are forced to update as well. +Cannot be used with \fB\-\-precise\fR\&. .RE .sp -\fB\-\-precise\fP \fIPRECISE\fP +\fB\-\-precise\fR \fIprecise\fR .RS 4 -When used with \fB\-p\fP, 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). +When used with \fB\-p\fR, 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). .RE .sp -\fB\-\-dry\-run\fP +\fB\-\-dry\-run\fR .RS 4 -Displays what would be updated, but doesn\(cqt actually write the lockfile. +Displays what would be updated, but doesn't actually write the lockfile. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -157,103 +114,74 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Update all dependencies in the lockfile: +\h'-04' 1.\h'+01'Update all dependencies in the lockfile: .sp -.if n .RS 4 +.RS 4 .nf cargo update .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Update only specific dependencies: +\h'-04' 2.\h'+01'Update only specific dependencies: .sp -.if n .RS 4 +.RS 4 .nf cargo update \-p foo \-p bar .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Set a specific dependency to a specific version: +\h'-04' 3.\h'+01'Set a specific dependency to a specific version: .sp -.if n .RS 4 +.RS 4 .nf cargo update \-p foo \-\-precise 1.2.3 .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-generate\-lockfile\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1) diff --git a/src/etc/man/cargo-vendor.1 b/src/etc/man/cargo-vendor.1 index f94be7ce0a5..bfdec7eb3e9 100644 --- a/src/etc/man/cargo-vendor.1 +++ b/src/etc/man/cargo-vendor.1 @@ -1,69 +1,44 @@ '\" t -.\" Title: cargo-vendor -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-VENDOR" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-VENDOR" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-vendor \- Vendor all dependencies locally .SH "SYNOPSIS" -.sp -\fBcargo vendor [\fIOPTIONS\fP] [\fIPATH\fP]\fP +\fBcargo vendor\fR [\fIoptions\fR] [\fIpath\fR] .SH "DESCRIPTION" -.sp This cargo subcommand will vendor all crates.io and git dependencies for a -project into the specified directory at \fB\fP. After this command completes -the vendor directory specified by \fB\fP will contain all remote sources from +project into the specified directory at \fB\fR\&. After this command completes +the vendor directory specified by \fB\fR will contain all remote sources from dependencies specified. Additional manifests beyond the default one can be -specified with the \fB\-s\fP option. +specified with the \fB\-s\fR option. .sp -The \fBcargo vendor\fP command will also print out the configuration necessary -to use the vendored sources, which you will need to add to \fB.cargo/config.toml\fP. +The \fBcargo vendor\fR command will also print out the configuration necessary +to use the vendored sources, which you will need to add to \fB\&.cargo/config.toml\fR\&. .SH "OPTIONS" .SS "Vendor Options" .sp -\fB\-s\fP \fIMANIFEST\fP, \fB\-\-sync\fP \fIMANIFEST\fP +\fB\-s\fR \fImanifest\fR, +\fB\-\-sync\fR \fImanifest\fR .RS 4 -Specify extra \fBCargo.toml\fP manifests to workspaces which should also be +Specify extra \fBCargo.toml\fR manifests to workspaces which should also be vendored and synced to the output. .RE .sp -\fB\-\-no\-delete\fP +\fB\-\-no\-delete\fR .RS 4 -Don\(cqt delete the "vendor" directory when vendoring, but rather keep all +Don't delete the "vendor" directory when vendoring, but rather keep all existing contents of the vendor directory .RE .sp -\fB\-\-respect\-source\-config\fP +\fB\-\-respect\-source\-config\fR .RS 4 -Instead of ignoring \fB[source]\fP configuration by default in \fB.cargo/config.toml\fP +Instead of ignoring \fB[source]\fR configuration by default in \fB\&.cargo/config.toml\fR read it and use it when downloading crates from crates.io, for example .RE .sp -\fB\-\-versioned\-dirs\fP +\fB\-\-versioned\-dirs\fR .RS 4 Normally versions are only added to disambiguate multiple versions of the same package. This option causes all directories in the "vendor" directory @@ -73,187 +48,140 @@ only a subset of the packages have changed. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +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. +.sp +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 \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... -.RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. -.RE -.sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-Z\fR \fIflag\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is -up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from -attempting to access the network to determine if it is out\-of\-date. -.sp -These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network -access. -.RE -.sp -\fB\-\-offline\fP -.RS 4 -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. -.sp -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 \fBcargo\-fetch\fP(1) command to download dependencies before going -offline. -.sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Vendor all dependencies into a local "vendor" folder +\h'-04' 1.\h'+01'Vendor all dependencies into a local "vendor" folder .sp -.if n .RS 4 +.RS 4 .nf cargo vendor .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Vendor all dependencies into a local "third\-party/vendor" folder +\h'-04' 2.\h'+01'Vendor all dependencies into a local "third\-party/vendor" folder .sp -.if n .RS 4 +.RS 4 .nf cargo vendor third\-party/vendor .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Vendor the current workspace as well as another to "vendor" +\h'-04' 3.\h'+01'Vendor the current workspace as well as another to "vendor" .sp -.if n .RS 4 +.RS 4 .nf cargo vendor \-s ../path/to/Cargo.toml .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) \ No newline at end of file +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-verify-project.1 b/src/etc/man/cargo-verify-project.1 index 00355dad25e..ed46e464bf9 100644 --- a/src/etc/man/cargo-verify-project.1 +++ b/src/etc/man/cargo-verify-project.1 @@ -1,133 +1,89 @@ '\" t -.\" Title: cargo-verify-project -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-VERIFY\-PROJECT" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-VERIFY\-PROJECT" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-verify\-project \- Check correctness of crate manifest .SH "SYNOPSIS" -.sp -\fBcargo verify\-project [\fIOPTIONS\fP]\fP +\fBcargo verify\-project\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp This command will parse the local manifest and check its validity. It emits a JSON object with the result. A successful validation will display: .sp -.if n .RS 4 +.RS 4 .nf {"success":"true"} .fi -.if n .RE +.RE .sp An invalid workspace will display: .sp -.if n .RS 4 +.RS 4 .nf {"invalid":"human\-readable error message"} .fi -.if n .RE +.RE .SH "OPTIONS" .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -137,69 +93,54 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -The workspace is OK. +\h'-04'\(bu\h'+02'\fB0\fR: The workspace is OK. .RE .sp -1 .RS 4 -The workspace is invalid. +\h'-04'\(bu\h'+02'\fB1\fR: The workspace is invalid. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Check the current workspace for errors: +\h'-04' 1.\h'+01'Check the current workspace for errors: .sp -.if n .RS 4 +.RS 4 .nf cargo verify\-project .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-package\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-package\fR(1) diff --git a/src/etc/man/cargo-version.1 b/src/etc/man/cargo-version.1 index 73946405f45..cabd8b2d240 100644 --- a/src/etc/man/cargo-version.1 +++ b/src/etc/man/cargo-version.1 @@ -1,99 +1,52 @@ '\" t -.\" Title: cargo-version -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-VERSION" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-VERSION" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-version \- Show version information .SH "SYNOPSIS" -.sp -\fBcargo version [\fIOPTIONS\fP]\fP +\fBcargo version\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Displays the version of Cargo. .SH "OPTIONS" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 Display additional version information. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Display the version: +\h'-04' 1.\h'+01'Display the version: .sp -.if n .RS 4 +.RS 4 .nf cargo version .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -The version is also available via flags: +\h'-04' 2.\h'+01'The version is also available via flags: .sp -.if n .RS 4 +.RS 4 .nf cargo \-\-version cargo \-V .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Display extra version information: +\h'-04' 3.\h'+01'Display extra version information: .sp -.if n .RS 4 +.RS 4 .nf cargo \-Vv .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) \ No newline at end of file +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1 index e6250e976b5..95fe1e3687c 100644 --- a/src/etc/man/cargo-yank.1 +++ b/src/etc/man/cargo-yank.1 @@ -1,204 +1,144 @@ '\" t -.\" Title: cargo-yank -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-YANK" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-YANK" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-yank \- Remove a pushed crate from the index .SH "SYNOPSIS" -.sp -\fBcargo yank [\fIOPTIONS\fP] \-\-vers \fIVERSION\fP [\fICRATE\fP]\fP +\fBcargo yank\fR [\fIoptions\fR] \fB\-\-vers\fR \fIversion\fR [\fIcrate\fR] .SH "DESCRIPTION" -.sp -The yank command removes a previously published crate\(cqs version from the -server\(cqs index. This command does not delete any data, and the crate will -still be available for download via the registry\(cqs download link. +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 +still be available for download via the registry's download link. .sp Note that existing crates locked to a yanked version will still be able to download the yanked version to use it. Cargo will, however, not allow any new crates to be locked to any yanked version. .sp -This command requires you to be authenticated with either the \fB\-\-token\fP option -or using \fBcargo\-login\fP(1). +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). .sp If the crate name is not specified, it will use the package name from the current directory. .SH "OPTIONS" .SS "Yank Options" .sp -\fB\-\-vers\fP \fIVERSION\fP +\fB\-\-vers\fR \fIversion\fR .RS 4 The version to yank or un\-yank. .RE .sp -\fB\-\-undo\fP +\fB\-\-undo\fR .RS 4 Undo a yank, putting a version back into the index. .RE .sp -\fB\-\-token\fP \fITOKEN\fP +\fB\-\-token\fR \fItoken\fR .RS 4 API token to use when authenticating. This overrides the token stored in -the credentials file (which is created by \fBcargo\-login\fP(1)). +the credentials file (which is created by \fBcargo\-login\fR(1)). .sp -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " " -environment variables can be +\fICargo config\fR environment variables can be used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment +crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment variable. Tokens for other registries may be specified with environment -variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name of the registry in all capital letters. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Yank a crate from the index: +\h'-04' 1.\h'+01'Yank a crate from the index: .sp -.if n .RS 4 +.RS 4 .nf cargo yank \-\-vers 1.0.7 foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-login\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 index aec7e552a22..22010483eb4 100644 --- a/src/etc/man/cargo.1 +++ b/src/etc/man/cargo.1 @@ -1,303 +1,222 @@ '\" t -.\" Title: cargo -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO" "1" .nh .ad l -.de URL -\fI\\$2\fP <\\$1>\\$3 -.. -.als MTO URL -.if \n[.g] \{\ -. mso www.tmac -. am URL -. ad l -. . -. am MTO -. ad l -. . -. LINKSTYLE blue R < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo \- The Rust package manager .SH "SYNOPSIS" -.sp -\fBcargo [\fIOPTIONS\fP] \fICOMMAND\fP [\fIARGS\fP]\fP +\fBcargo\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR] .br -\fBcargo [\fIOPTIONS\fP] \-\-version\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-version\fR .br -\fBcargo [\fIOPTIONS\fP] \-\-list\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-list\fR .br -\fBcargo [\fIOPTIONS\fP] \-\-help\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-help\fR .br -\fBcargo [\fIOPTIONS\fP] \-\-explain \fICODE\fP\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-explain\fR \fIcode\fR .SH "DESCRIPTION" -.sp This program is a package manager and build tool for the Rust language, -available at \c -.URL "https://rust\-lang.org" "" "." +available at \&. .SH "COMMANDS" .SS "Build Commands" +\fBcargo\-bench\fR(1) +.br +\ \ \ \ Execute benchmarks of a package. .sp -\fBcargo\-bench\fP(1) -.RS 4 -Execute benchmarks of a package. -.RE -.sp -\fBcargo\-build\fP(1) -.RS 4 -Compile a package. -.RE +\fBcargo\-build\fR(1) +.br +\ \ \ \ Compile a package. .sp -\fBcargo\-check\fP(1) -.RS 4 -Check a local package and all of its dependencies for errors. -.RE +\fBcargo\-check\fR(1) +.br +\ \ \ \ Check a local package and all of its dependencies for errors. .sp -\fBcargo\-clean\fP(1) -.RS 4 -Remove artifacts that Cargo has generated in the past. -.RE +\fBcargo\-clean\fR(1) +.br +\ \ \ \ Remove artifacts that Cargo has generated in the past. .sp -\fBcargo\-doc\fP(1) -.RS 4 -Build a package\(cqs documentation. -.RE +\fBcargo\-doc\fR(1) +.br +\ \ \ \ Build a package's documentation. .sp -\fBcargo\-fetch\fP(1) -.RS 4 -Fetch dependencies of a package from the network. -.RE +\fBcargo\-fetch\fR(1) +.br +\ \ \ \ Fetch dependencies of a package from the network. .sp -\fBcargo\-fix\fP(1) -.RS 4 -Automatically fix lint warnings reported by rustc. -.RE +\fBcargo\-fix\fR(1) +.br +\ \ \ \ Automatically fix lint warnings reported by rustc. .sp -\fBcargo\-run\fP(1) -.RS 4 -Run a binary or example of the local package. -.RE +\fBcargo\-run\fR(1) +.br +\ \ \ \ Run a binary or example of the local package. .sp -\fBcargo\-rustc\fP(1) -.RS 4 -Compile a package, and pass extra options to the compiler. -.RE +\fBcargo\-rustc\fR(1) +.br +\ \ \ \ Compile a package, and pass extra options to the compiler. .sp -\fBcargo\-rustdoc\fP(1) -.RS 4 -Build a package\(cqs documentation, using specified custom flags. -.RE +\fBcargo\-rustdoc\fR(1) +.br +\ \ \ \ Build a package's documentation, using specified custom flags. .sp -\fBcargo\-test\fP(1) -.RS 4 -Execute unit and integration tests of a package. -.RE +\fBcargo\-test\fR(1) +.br +\ \ \ \ Execute unit and integration tests of a package. .SS "Manifest Commands" +\fBcargo\-generate\-lockfile\fR(1) +.br +\ \ \ \ Generate \fBCargo.lock\fR for a project. .sp -\fBcargo\-generate\-lockfile\fP(1) -.RS 4 -Generate \fBCargo.lock\fP for a project. -.RE -.sp -\fBcargo\-locate\-project\fP(1) -.RS 4 -Print a JSON representation of a \fBCargo.toml\fP file\(cqs location. -.RE +\fBcargo\-locate\-project\fR(1) +.br +\ \ \ \ Print a JSON representation of a \fBCargo.toml\fR file's location. .sp -\fBcargo\-metadata\fP(1) -.RS 4 -Output the resolved dependencies of a package, the concrete used versions -including overrides, in machine\-readable format. -.RE +\fBcargo\-metadata\fR(1) +.br +\ \ \ \ Output the resolved dependencies of a package in machine\-readable format. .sp -\fBcargo\-pkgid\fP(1) -.RS 4 -Print a fully qualified package specification. -.RE +\fBcargo\-pkgid\fR(1) +.br +\ \ \ \ Print a fully qualified package specification. .sp -\fBcargo\-tree\fP(1) -.RS 4 -Display a tree visualization of a dependency graph. -.RE +\fBcargo\-tree\fR(1) +.br +\ \ \ \ Display a tree visualization of a dependency graph. .sp -\fBcargo\-update\fP(1) -.RS 4 -Update dependencies as recorded in the local lock file. -.RE +\fBcargo\-update\fR(1) +.br +\ \ \ \ Update dependencies as recorded in the local lock file. .sp -\fBcargo\-vendor\fP(1) -.RS 4 -Vendor all dependencies locally. -.RE +\fBcargo\-vendor\fR(1) +.br +\ \ \ \ Vendor all dependencies locally. .sp -\fBcargo\-verify\-project\fP(1) -.RS 4 -Check correctness of crate manifest. -.RE +\fBcargo\-verify\-project\fR(1) +.br +\ \ \ \ Check correctness of crate manifest. .SS "Package Commands" +\fBcargo\-init\fR(1) +.br +\ \ \ \ Create a new Cargo package in an existing directory. .sp -\fBcargo\-init\fP(1) -.RS 4 -Create a new Cargo package in an existing directory. -.RE -.sp -\fBcargo\-install\fP(1) -.RS 4 -Build and install a Rust binary. -.RE +\fBcargo\-install\fR(1) +.br +\ \ \ \ Build and install a Rust binary. .sp -\fBcargo\-new\fP(1) -.RS 4 -Create a new Cargo package. -.RE +\fBcargo\-new\fR(1) +.br +\ \ \ \ Create a new Cargo package. .sp -\fBcargo\-search\fP(1) -.RS 4 -Search packages in crates.io. -.RE +\fBcargo\-search\fR(1) +.br +\ \ \ \ Search packages in crates.io. .sp -\fBcargo\-uninstall\fP(1) -.RS 4 -Remove a Rust binary. -.RE +\fBcargo\-uninstall\fR(1) +.br +\ \ \ \ Remove a Rust binary. .SS "Publishing Commands" +\fBcargo\-login\fR(1) +.br +\ \ \ \ Save an API token from the registry locally. .sp -\fBcargo\-login\fP(1) -.RS 4 -Save an API token from the registry locally. -.RE -.sp -\fBcargo\-owner\fP(1) -.RS 4 -Manage the owners of a crate on the registry. -.RE +\fBcargo\-owner\fR(1) +.br +\ \ \ \ Manage the owners of a crate on the registry. .sp -\fBcargo\-package\fP(1) -.RS 4 -Assemble the local package into a distributable tarball. -.RE +\fBcargo\-package\fR(1) +.br +\ \ \ \ Assemble the local package into a distributable tarball. .sp -\fBcargo\-publish\fP(1) -.RS 4 -Upload a package to the registry. -.RE +\fBcargo\-publish\fR(1) +.br +\ \ \ \ Upload a package to the registry. .sp -\fBcargo\-yank\fP(1) -.RS 4 -Remove a pushed crate from the index. -.RE +\fBcargo\-yank\fR(1) +.br +\ \ \ \ Remove a pushed crate from the index. .SS "General Commands" +\fBcargo\-help\fR(1) +.br +\ \ \ \ Display help information about Cargo. .sp -\fBcargo\-help\fP(1) -.RS 4 -Display help information about Cargo. -.RE -.sp -\fBcargo\-version\fP(1) -.RS 4 -Show version information. -.RE +\fBcargo\-version\fR(1) +.br +\ \ \ \ Show version information. .SH "OPTIONS" .SS "Special Options" .sp -\fB\-V\fP, \fB\-\-version\fP +\fB\-V\fR, +\fB\-\-version\fR .RS 4 -Print version info and exit. If used with \fB\-\-verbose\fP, prints extra +Print version info and exit. If used with \fB\-\-verbose\fR, prints extra information. .RE .sp -\fB\-\-list\fP +\fB\-\-list\fR .RS 4 -List all installed Cargo subcommands. If used with \fB\-\-verbose\fP, prints -extra information. +List all installed Cargo subcommands. If used with \fB\-\-verbose\fR, prints extra +information. .RE .sp -\fB\-\-explain \fICODE\fP\fP +\fB\-\-explain\fR \fIcode\fR .RS 4 -Run \fBrustc \-\-explain CODE\fP which will print out a detailed explanation of -an error message (for example, \fBE0004\fP). +Run \fBrustc \-\-explain CODE\fR which will print out a detailed explanation of an +error message (for example, \fBE0004\fR). .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 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 \fBterm.verbose\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .RS 4 Control when colored output is used. Valid values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBauto\fP (default): Automatically detect if color support is available on the +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the terminal. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBalways\fP: Always display colors. +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnever\fP: Never display colors. +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. .RE .sp -May also be specified with the \fBterm.color\fP -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 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 @@ -307,207 +226,145 @@ 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 \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "FILES" +\fB~/.cargo/\fR +.br +\ \ \ \ Default location for Cargo's "home" directory where it +stores various files. The location can be changed with the \fBCARGO_HOME\fR +environment variable. .sp -\fB~/.cargo/\fP -.RS 4 -Default location for Cargo\(cqs "home" directory where it stores various -files. The location can be changed with the \fBCARGO_HOME\fP environment -variable. -.RE -.sp -\fB$CARGO_HOME/bin/\fP -.RS 4 -Binaries installed by \fBcargo\-install\fP(1) will be located here. If using +\fB$CARGO_HOME/bin/\fR +.br +\ \ \ \ Binaries installed by \fBcargo\-install\fR(1) will be located here. If using rustup, executables distributed with Rust are also located here. -.RE .sp -\fB$CARGO_HOME/config.toml\fP -.RS 4 -The global configuration file. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" +\fB$CARGO_HOME/config.toml\fR +.br +\ \ \ \ The global configuration file. See \fIthe reference\fR for more information about configuration files. -.RE .sp -\fB.cargo/config.toml\fP -.RS 4 -Cargo automatically searches for a file named \fB.cargo/config.toml\fP in the +\fB\&.cargo/config.toml\fR +.br +\ \ \ \ Cargo automatically searches for a file named \fB\&.cargo/config.toml\fR in the current directory, and all parent directories. These configuration files will be merged with the global configuration file. -.RE .sp -\fB$CARGO_HOME/credentials.toml\fP -.RS 4 -Private authentication information for logging in to a registry. -.RE +\fB$CARGO_HOME/credentials.toml\fR +.br +\ \ \ \ Private authentication information for logging in to a registry. .sp -\fB$CARGO_HOME/registry/\fP -.RS 4 -This directory contains cached downloads of the registry index and any +\fB$CARGO_HOME/registry/\fR +.br +\ \ \ \ This directory contains cached downloads of the registry index and any downloaded dependencies. -.RE .sp -\fB$CARGO_HOME/git/\fP -.RS 4 -This directory contains cached downloads of git dependencies. -.RE +\fB$CARGO_HOME/git/\fR +.br +\ \ \ \ This directory contains cached downloads of git dependencies. .sp -Please note that the internal structure of the \fB$CARGO_HOME\fP directory is not +Please note that the internal structure of the \fB$CARGO_HOME\fR directory is not stable yet and may be subject to change. .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Build a local package and all of its dependencies: -.sp -.if n .RS 4 +\h'-04' 1.\h'+01'Build a local package and all of its dependencies: +.sp +.RS 4 .nf cargo build .fi -.if n .RE .RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Build a package with optimizations: .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Build a package with optimizations: -.sp -.if n .RS 4 .nf cargo build \-\-release .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Run tests for a cross\-compiled target: -.sp -.if n .RS 4 +\h'-04' 3.\h'+01'Run tests for a cross\-compiled target: +.sp +.RS 4 .nf cargo test \-\-target i686\-unknown\-linux\-gnu .fi -.if n .RE .RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Create a new package that builds an executable: .sp .RS 4 -.ie n \{\ -\h'-04' 4.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 4." 4.2 -.\} -Create a new package that builds an executable: -.sp -.if n .RS 4 .nf cargo new foobar .fi -.if n .RE .RE +.RE +.sp +.RS 4 +\h'-04' 5.\h'+01'Create a package in the current directory: .sp .RS 4 -.ie n \{\ -\h'-04' 5.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 5." 4.2 -.\} -Create a package in the current directory: -.sp -.if n .RS 4 .nf mkdir foo && cd foo cargo init . .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 6.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 6." 4.2 -.\} -Learn about a command\(cqs options and usage: -.sp -.if n .RS 4 +\h'-04' 6.\h'+01'Learn about a command's options and usage: +.sp +.RS 4 .nf cargo help clean .fi -.if n .RE +.RE .RE .SH "BUGS" -.sp -See \c -.URL "https://github.com/rust\-lang/cargo/issues" "" " " -for issues. +See for issues. .SH "SEE ALSO" -.sp -\fBrustc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file +\fBrustc\fR(1), \fBrustdoc\fR(1)