From: Eric Huss Date: Sat, 1 Aug 2020 16:33:06 +0000 (-0700) Subject: Move asciidoc man pages to markdown. X-Git-Url: https://git.proxmox.com/?a=commitdiff_plain;h=5594bfa4bde59eaedfdff6c1e77ee215f978e0e2;p=cargo.git Move asciidoc man pages to markdown. --- diff --git a/src/doc/man/cargo-bench.adoc b/src/doc/man/cargo-bench.adoc deleted file mode 100644 index 79acc6f26..000000000 --- a/src/doc/man/cargo-bench.adoc +++ /dev/null @@ -1,152 +0,0 @@ -= cargo-bench(1) -:idprefix: cargo_bench_ -:doctype: manpage -:actionverb: Benchmark -:nouns: benchmarks - -== 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're passing arguments to both Cargo and the binary, the ones after `--` go -to the binary, the ones before go to Cargo. For details about libtest's -arguments see the output of `cargo bench \-- --help`. As an example, this will -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 -> link:https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html[`#[bench\]` attribute] -> is currently unstable and only available on the -> link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel]. -> There are some packages available on -> link:https://crates.io/keywords/benchmark[crates.io] that may help with -> running benchmarks on the stable channel, such as -> link:https://crates.io/crates/criterion[Criterion]. - -== OPTIONS - -=== Benchmark Options - -include::options-test.adoc[] - -=== Package Selection - -include::options-packages.adoc[] - -=== 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. - -include::options-targets.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== 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 - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -The `--jobs` argument affects the building of the benchmark executable but -does not affect how many threads are used when running the benchmarks. The -Rust test harness runs benchmarks serially in a single thread. - -include::options-jobs.adoc[] - -== PROFILES - -Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -linkcargo:reference/profiles.html[the reference] -for more details. - -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 -man:cargo-build[1] which will use the `test` profile which is by default -unoptimized and includes debug information. You can then run the debug-enabled -benchmark manually. - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Build and execute all the benchmarks of the current package: - - cargo bench - -. Run only a specific benchmark within a specific benchmark target: - - cargo bench --bench bench_name -- modname::some_benchmark - -== SEE ALSO -man:cargo[1], man:cargo-test[1] diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md new file mode 100644 index 000000000..79acc6f26 --- /dev/null +++ b/src/doc/man/cargo-bench.md @@ -0,0 +1,152 @@ += cargo-bench(1) +:idprefix: cargo_bench_ +:doctype: manpage +:actionverb: Benchmark +:nouns: benchmarks + +== 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're passing arguments to both Cargo and the binary, the ones after `--` go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of `cargo bench \-- --help`. As an example, this will +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 +> link:https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html[`#[bench\]` attribute] +> is currently unstable and only available on the +> link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel]. +> There are some packages available on +> link:https://crates.io/keywords/benchmark[crates.io] that may help with +> running benchmarks on the stable channel, such as +> link:https://crates.io/crates/criterion[Criterion]. + +== OPTIONS + +=== Benchmark Options + +include::options-test.adoc[] + +=== Package Selection + +include::options-packages.adoc[] + +=== 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. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== 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 + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +The `--jobs` argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread. + +include::options-jobs.adoc[] + +== PROFILES + +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +linkcargo:reference/profiles.html[the reference] +for more details. + +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 +man:cargo-build[1] which will use the `test` profile which is by default +unoptimized and includes debug information. You can then run the debug-enabled +benchmark manually. + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build and execute all the benchmarks of the current package: + + cargo bench + +. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +== SEE ALSO +man:cargo[1], man:cargo-test[1] diff --git a/src/doc/man/cargo-build.adoc b/src/doc/man/cargo-build.adoc deleted file mode 100644 index a7b20d7de..000000000 --- a/src/doc/man/cargo-build.adoc +++ /dev/null @@ -1,98 +0,0 @@ -= cargo-build(1) -:idprefix: cargo_build_ -:doctype: manpage -:actionverb: Build - -== NAME - -cargo-build - Compile the current package - -== SYNOPSIS - -`cargo build [_OPTIONS_]` - -== DESCRIPTION - -Compile local packages and all of their dependencies. - -== OPTIONS - -=== Package Selection - -include::options-packages.adoc[] - -=== Target Selection - -When no target selection options are given, `cargo build` will build all -binary and library targets of the selected packages. Binaries are skipped if -they have `required-features` that are missing. - -include::options-targets.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -*--out-dir* _DIRECTORY_:: - Copy final artifacts to this directory. -+ -This option is unstable and available only on the -link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel] -and requires the `-Z unstable-options` flag to enable. -See https://github.com/rust-lang/cargo/issues/6790 for more information. - -=== Display Options - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -*--build-plan*:: - Outputs a series of JSON messages to stdout that indicate the commands to - run the build. -+ -This option is unstable and available only on the -link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel] -and requires the `-Z unstable-options` flag to enable. -See https://github.com/rust-lang/cargo/issues/5579 for more information. - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Build the local package and all of its dependencies: - - cargo build - -. Build with optimizations: - - cargo build --release - -== SEE ALSO -man:cargo[1], man:cargo-rustc[1] diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md new file mode 100644 index 000000000..a7b20d7de --- /dev/null +++ b/src/doc/man/cargo-build.md @@ -0,0 +1,98 @@ += cargo-build(1) +:idprefix: cargo_build_ +:doctype: manpage +:actionverb: Build + +== NAME + +cargo-build - Compile the current package + +== SYNOPSIS + +`cargo build [_OPTIONS_]` + +== DESCRIPTION + +Compile local packages and all of their dependencies. + +== OPTIONS + +=== Package Selection + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo build` will build all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +*--out-dir* _DIRECTORY_:: + Copy final artifacts to this directory. ++ +This option is unstable and available only on the +link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel] +and requires the `-Z unstable-options` flag to enable. +See https://github.com/rust-lang/cargo/issues/6790 for more information. + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +*--build-plan*:: + Outputs a series of JSON messages to stdout that indicate the commands to + run the build. ++ +This option is unstable and available only on the +link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel] +and requires the `-Z unstable-options` flag to enable. +See https://github.com/rust-lang/cargo/issues/5579 for more information. + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build the local package and all of its dependencies: + + cargo build + +. Build with optimizations: + + cargo build --release + +== SEE ALSO +man:cargo[1], man:cargo-rustc[1] diff --git a/src/doc/man/cargo-check.adoc b/src/doc/man/cargo-check.adoc deleted file mode 100644 index c84b1dcef..000000000 --- a/src/doc/man/cargo-check.adoc +++ /dev/null @@ -1,87 +0,0 @@ -= cargo-check(1) -:idprefix: cargo_check_ -:doctype: manpage -:actionverb: Check - -== 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 - -include::options-packages.adoc[] - -=== Target Selection - -When no target selection options are given, `cargo check` will check all -binary and library targets of the selected packages. Binaries are skipped if -they have `required-features` that are missing. - -include::options-targets.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -include::options-profile.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== Display Options - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Check the local package for errors: - - cargo check - -. Check all targets, including unit tests: - - cargo check --all-targets --profile=test - -== SEE ALSO -man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md new file mode 100644 index 000000000..c84b1dcef --- /dev/null +++ b/src/doc/man/cargo-check.md @@ -0,0 +1,87 @@ += cargo-check(1) +:idprefix: cargo_check_ +:doctype: manpage +:actionverb: Check + +== 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 + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo check` will check all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +include::options-profile.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Check the local package for errors: + + cargo check + +. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +== SEE ALSO +man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-clean.adoc b/src/doc/man/cargo-clean.adoc deleted file mode 100644 index 08fdb76de..000000000 --- a/src/doc/man/cargo-clean.adoc +++ /dev/null @@ -1,76 +0,0 @@ -= cargo-clean(1) -:idprefix: cargo_clean_ -:doctype: manpage -:actionverb: Clean - -== 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 man: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. - -include::options-target-dir.adoc[] - -include::options-target-triple.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Remove the entire target directory: - - cargo clean - -. Remove only the release artifacts: - - cargo clean --release - -== SEE ALSO -man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-clean.md b/src/doc/man/cargo-clean.md new file mode 100644 index 000000000..08fdb76de --- /dev/null +++ b/src/doc/man/cargo-clean.md @@ -0,0 +1,76 @@ += cargo-clean(1) +:idprefix: cargo_clean_ +:doctype: manpage +:actionverb: Clean + +== 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 man: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. + +include::options-target-dir.adoc[] + +include::options-target-triple.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Remove the entire target directory: + + cargo clean + +. Remove only the release artifacts: + + cargo clean --release + +== SEE ALSO +man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-doc.adoc b/src/doc/man/cargo-doc.adoc deleted file mode 100644 index 70e37dff9..000000000 --- a/src/doc/man/cargo-doc.adoc +++ /dev/null @@ -1,97 +0,0 @@ -= cargo-doc(1) -:idprefix: cargo_doc_ -:doctype: manpage -:actionverb: Document - -== 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 - -include::options-packages.adoc[] - -=== 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. - -include::options-targets-lib-bin.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== Display Options - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Build the local package documentation and its dependencies and output to -`target/doc`. - - cargo doc - -== SEE ALSO -man:cargo[1], man:cargo-rustdoc[1], man:rustdoc[1] diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md new file mode 100644 index 000000000..70e37dff9 --- /dev/null +++ b/src/doc/man/cargo-doc.md @@ -0,0 +1,97 @@ += cargo-doc(1) +:idprefix: cargo_doc_ +:doctype: manpage +:actionverb: Document + +== 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 + +include::options-packages.adoc[] + +=== 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. + +include::options-targets-lib-bin.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build the local package documentation and its dependencies and output to +`target/doc`. + + cargo doc + +== SEE ALSO +man:cargo[1], man:cargo-rustdoc[1], man:rustdoc[1] diff --git a/src/doc/man/cargo-fetch.adoc b/src/doc/man/cargo-fetch.adoc deleted file mode 100644 index 3a12882b1..000000000 --- a/src/doc/man/cargo-fetch.adoc +++ /dev/null @@ -1,61 +0,0 @@ -= cargo-fetch(1) -:idprefix: cargo_fetch_ -:doctype: manpage -:actionverb: Fetch - -== 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 link:https://crates.io/crates/cargo-prefetch[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 - -include::options-target-triple.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Fetch all dependencies: - - cargo fetch - -== SEE ALSO -man:cargo[1], man:cargo-update[1], man:cargo-generate-lockfile[1] diff --git a/src/doc/man/cargo-fetch.md b/src/doc/man/cargo-fetch.md new file mode 100644 index 000000000..3a12882b1 --- /dev/null +++ b/src/doc/man/cargo-fetch.md @@ -0,0 +1,61 @@ += cargo-fetch(1) +:idprefix: cargo_fetch_ +:doctype: manpage +:actionverb: Fetch + +== 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 link:https://crates.io/crates/cargo-prefetch[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 + +include::options-target-triple.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Fetch all dependencies: + + cargo fetch + +== SEE ALSO +man:cargo[1], man:cargo-update[1], man:cargo-generate-lockfile[1] diff --git a/src/doc/man/cargo-fix.adoc b/src/doc/man/cargo-fix.adoc deleted file mode 100644 index 0cc8c3da4..000000000 --- a/src/doc/man/cargo-fix.adoc +++ /dev/null @@ -1,142 +0,0 @@ -= cargo-fix(1) -:idprefix: cargo_fix_ -:doctype: manpage -:actionverb: Fix - -== 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 man:cargo-check[1]. Any warnings -applicable to your crate will be automatically fixed (if possible) and all -remaining warnings will be displayed when the check process is finished. For -example if you'd like to prepare for the 2018 edition, you can do so by -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 -https://github.com/rust-lang/cargo - -== 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 - -include::options-packages.adoc[] - -=== Target Selection - -When no target selection options are given, `cargo fix` will fix all targets -(`--all-targets` implied). Binaries are skipped if they have -`required-features` that are missing. - -include::options-targets.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -include::options-profile.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== Display Options - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Apply compiler suggestions to the local package: - - cargo fix - -. Convert a 2015 edition to 2018: - - cargo fix --edition - -. Apply suggested idioms for the current edition: - - cargo fix --edition-idioms - -== SEE ALSO -man:cargo[1], man:cargo-check[1] diff --git a/src/doc/man/cargo-fix.md b/src/doc/man/cargo-fix.md new file mode 100644 index 000000000..0cc8c3da4 --- /dev/null +++ b/src/doc/man/cargo-fix.md @@ -0,0 +1,142 @@ += cargo-fix(1) +:idprefix: cargo_fix_ +:doctype: manpage +:actionverb: Fix + +== 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 man:cargo-check[1]. Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you'd like to prepare for the 2018 edition, you can do so by +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 +https://github.com/rust-lang/cargo + +== 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 + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo fix` will fix all targets +(`--all-targets` implied). Binaries are skipped if they have +`required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +include::options-profile.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Apply compiler suggestions to the local package: + + cargo fix + +. Convert a 2015 edition to 2018: + + cargo fix --edition + +. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +== SEE ALSO +man:cargo[1], man:cargo-check[1] diff --git a/src/doc/man/cargo-generate-lockfile.adoc b/src/doc/man/cargo-generate-lockfile.adoc deleted file mode 100644 index 2b8915978..000000000 --- a/src/doc/man/cargo-generate-lockfile.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= cargo-generate-lockfile(1) -:idprefix: cargo_generate-lockfile_ -:doctype: manpage - -== 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 man:cargo-update[1] which is also capable of creating a `Cargo.lock` -lockfile and has more options for controlling update behavior. - -== OPTIONS - -=== Display Options - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Create or update the lockfile for the current package or workspace: - - cargo generate-lockfile - -== SEE ALSO -man:cargo[1], man:cargo-update[1] diff --git a/src/doc/man/cargo-generate-lockfile.md b/src/doc/man/cargo-generate-lockfile.md new file mode 100644 index 000000000..2b8915978 --- /dev/null +++ b/src/doc/man/cargo-generate-lockfile.md @@ -0,0 +1,49 @@ += cargo-generate-lockfile(1) +:idprefix: cargo_generate-lockfile_ +:doctype: manpage + +== 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 man:cargo-update[1] which is also capable of creating a `Cargo.lock` +lockfile and has more options for controlling update behavior. + +== OPTIONS + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +== SEE ALSO +man:cargo[1], man:cargo-update[1] diff --git a/src/doc/man/cargo-help.adoc b/src/doc/man/cargo-help.adoc deleted file mode 100644 index bcbb5ba34..000000000 --- a/src/doc/man/cargo-help.adoc +++ /dev/null @@ -1,28 +0,0 @@ -= cargo-help(1) -:idprefix: cargo_help_ -:doctype: manpage - -== NAME - -cargo-help - Get help for a Cargo command - -== SYNOPSIS - -`cargo help [_SUBCOMMAND_]` - -== DESCRIPTION - -Prints a help message for the given command. - -== EXAMPLES - -. Get help for a command: - - cargo help build - -. Help is also available with the `--help` flag: - - cargo build --help - -== SEE ALSO -man:cargo[1] diff --git a/src/doc/man/cargo-help.md b/src/doc/man/cargo-help.md new file mode 100644 index 000000000..bcbb5ba34 --- /dev/null +++ b/src/doc/man/cargo-help.md @@ -0,0 +1,28 @@ += cargo-help(1) +:idprefix: cargo_help_ +:doctype: manpage + +== NAME + +cargo-help - Get help for a Cargo command + +== SYNOPSIS + +`cargo help [_SUBCOMMAND_]` + +== DESCRIPTION + +Prints a help message for the given command. + +== EXAMPLES + +. Get help for a command: + + cargo help build + +. Help is also available with the `--help` flag: + + cargo build --help + +== SEE ALSO +man:cargo[1] diff --git a/src/doc/man/cargo-init.adoc b/src/doc/man/cargo-init.adoc deleted file mode 100644 index 6df38bf68..000000000 --- a/src/doc/man/cargo-init.adoc +++ /dev/null @@ -1,55 +0,0 @@ -= cargo-init(1) -:idprefix: cargo_init_ -:doctype: manpage - -== 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). - -include::description-new-authors.adoc[] - -See man:cargo-new[1] for a similar command which will create a new package in -a new directory. - -== OPTIONS - -=== Init Options - -include::options-new.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Create a binary Cargo package in the current directory: - - cargo init - -== SEE ALSO -man:cargo[1], man:cargo-new[1] diff --git a/src/doc/man/cargo-init.md b/src/doc/man/cargo-init.md new file mode 100644 index 000000000..6df38bf68 --- /dev/null +++ b/src/doc/man/cargo-init.md @@ -0,0 +1,55 @@ += cargo-init(1) +:idprefix: cargo_init_ +:doctype: manpage + +== 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). + +include::description-new-authors.adoc[] + +See man:cargo-new[1] for a similar command which will create a new package in +a new directory. + +== OPTIONS + +=== Init Options + +include::options-new.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create a binary Cargo package in the current directory: + + cargo init + +== SEE ALSO +man:cargo[1], man:cargo-new[1] diff --git a/src/doc/man/cargo-install.adoc b/src/doc/man/cargo-install.adoc deleted file mode 100644 index 6c96fdcf9..000000000 --- a/src/doc/man/cargo-install.adoc +++ /dev/null @@ -1,186 +0,0 @@ -= cargo-install(1) -:idprefix: cargo_install_ -:doctype: manpage -:actionverb: Install - -== NAME - -cargo-install - Build and install a Rust binary - -== SYNOPSIS - -[%hardbreaks] -`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. - -include::description-install-root.adoc[] - -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 - linkcargo:reference/specifying-dependencies.md[version requirement], like - `~1.2`, to have Cargo select the newest version from the given - requirement. If the version does not have a requirement operator (such as - `^` or `~`), then it must be in the form _MAJOR.MINOR.PATCH_, and will - install exactly that version; it is *not* treated as a caret requirement - like Cargo dependencies are. - -*--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. - -include::options-registry.adoc[] - -include::options-index.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-target-dir.adoc[] - -*--debug*:: - Build with the `dev` profile instead the `release` profile. - -=== Manifest Options - -include::options-locked.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Install or upgrade a package from crates.io: - - cargo install ripgrep - -. Install or reinstall the package in the current directory: - - cargo install --path . - -. View the list of installed packages: - - cargo install --list - -== SEE ALSO -man:cargo[1], man:cargo-uninstall[1], man:cargo-search[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-install.md b/src/doc/man/cargo-install.md new file mode 100644 index 000000000..6c96fdcf9 --- /dev/null +++ b/src/doc/man/cargo-install.md @@ -0,0 +1,186 @@ += cargo-install(1) +:idprefix: cargo_install_ +:doctype: manpage +:actionverb: Install + +== NAME + +cargo-install - Build and install a Rust binary + +== SYNOPSIS + +[%hardbreaks] +`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. + +include::description-install-root.adoc[] + +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 + linkcargo:reference/specifying-dependencies.md[version requirement], like + `~1.2`, to have Cargo select the newest version from the given + requirement. If the version does not have a requirement operator (such as + `^` or `~`), then it must be in the form _MAJOR.MINOR.PATCH_, and will + install exactly that version; it is *not* treated as a caret requirement + like Cargo dependencies are. + +*--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. + +include::options-registry.adoc[] + +include::options-index.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-target-dir.adoc[] + +*--debug*:: + Build with the `dev` profile instead the `release` profile. + +=== Manifest Options + +include::options-locked.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Install or upgrade a package from crates.io: + + cargo install ripgrep + +. Install or reinstall the package in the current directory: + + cargo install --path . + +. View the list of installed packages: + + cargo install --list + +== SEE ALSO +man:cargo[1], man:cargo-uninstall[1], man:cargo-search[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-locate-project.adoc b/src/doc/man/cargo-locate-project.adoc deleted file mode 100644 index adfc7a39e..000000000 --- a/src/doc/man/cargo-locate-project.adoc +++ /dev/null @@ -1,46 +0,0 @@ -= cargo-locate-project(1) -:idprefix: cargo_locate-project_ -:doctype: manpage - -== 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 man:cargo-metadata[1] which is capable of returning the path to a -workspace root. - -== OPTIONS - -=== Display Options - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Display the path to the manifest based on the current directory: - - cargo locate-project - -== SEE ALSO -man:cargo[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-locate-project.md b/src/doc/man/cargo-locate-project.md new file mode 100644 index 000000000..adfc7a39e --- /dev/null +++ b/src/doc/man/cargo-locate-project.md @@ -0,0 +1,46 @@ += cargo-locate-project(1) +:idprefix: cargo_locate-project_ +:doctype: manpage + +== 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 man:cargo-metadata[1] which is capable of returning the path to a +workspace root. + +== OPTIONS + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Display the path to the manifest based on the current directory: + + cargo locate-project + +== SEE ALSO +man:cargo[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-login.adoc b/src/doc/man/cargo-login.adoc deleted file mode 100644 index 2d3a8e752..000000000 --- a/src/doc/man/cargo-login.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= cargo-login(1) -:idprefix: cargo_login_ -:doctype: manpage - -== 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 man:cargo-publish[1], will be automatically -authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` -defaults to `.cargo` in your home directory. - -If the _TOKEN_ argument is not specified, it will be read from stdin. - -The API token for crates.io may be retrieved from https://crates.io/me. - -Take care to keep the token secret, it should not be shared with anyone else. - -== OPTIONS - -=== Login Options - -include::options-registry.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Save the API token to disk: - - cargo login - -== SEE ALSO -man:cargo[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-login.md b/src/doc/man/cargo-login.md new file mode 100644 index 000000000..2d3a8e752 --- /dev/null +++ b/src/doc/man/cargo-login.md @@ -0,0 +1,51 @@ += cargo-login(1) +:idprefix: cargo_login_ +:doctype: manpage + +== 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 man:cargo-publish[1], will be automatically +authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` +defaults to `.cargo` in your home directory. + +If the _TOKEN_ argument is not specified, it will be read from stdin. + +The API token for crates.io may be retrieved from https://crates.io/me. + +Take care to keep the token secret, it should not be shared with anyone else. + +== OPTIONS + +=== Login Options + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Save the API token to disk: + + cargo login + +== SEE ALSO +man:cargo[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-metadata.adoc b/src/doc/man/cargo-metadata.adoc deleted file mode 100644 index 09a865a7a..000000000 --- a/src/doc/man/cargo-metadata.adoc +++ /dev/null @@ -1,333 +0,0 @@ -= cargo-metadata(1) -:idprefix: cargo_metadata_ -:doctype: manpage -: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 link:https://crates.io/crates/cargo_metadata[cargo_metadata crate] -for a Rust API for reading the metadata. - -== OUTPUT FORMAT - -The output has the following format: - -[source,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`. - -include::options-features.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Output JSON about the current package: - - cargo metadata --format-version=1 - -== SEE ALSO -man:cargo[1] diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md new file mode 100644 index 000000000..09a865a7a --- /dev/null +++ b/src/doc/man/cargo-metadata.md @@ -0,0 +1,333 @@ += cargo-metadata(1) +:idprefix: cargo_metadata_ +:doctype: manpage +: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 link:https://crates.io/crates/cargo_metadata[cargo_metadata crate] +for a Rust API for reading the metadata. + +== OUTPUT FORMAT + +The output has the following format: + +[source,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`. + +include::options-features.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Output JSON about the current package: + + cargo metadata --format-version=1 + +== SEE ALSO +man:cargo[1] diff --git a/src/doc/man/cargo-new.adoc b/src/doc/man/cargo-new.adoc deleted file mode 100644 index 6587a3789..000000000 --- a/src/doc/man/cargo-new.adoc +++ /dev/null @@ -1,50 +0,0 @@ -= cargo-new(1) -:idprefix: cargo_new_ -:doctype: manpage - -== 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). - -include::description-new-authors.adoc[] - -See man:cargo-init[1] for a similar command which will create a new manifest -in an existing directory. - -== OPTIONS - -=== New Options - -include::options-new.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Create a binary Cargo package in the given directory: - - cargo new foo - -== SEE ALSO -man:cargo[1], man:cargo-init[1] diff --git a/src/doc/man/cargo-new.md b/src/doc/man/cargo-new.md new file mode 100644 index 000000000..6587a3789 --- /dev/null +++ b/src/doc/man/cargo-new.md @@ -0,0 +1,50 @@ += cargo-new(1) +:idprefix: cargo_new_ +:doctype: manpage + +== 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). + +include::description-new-authors.adoc[] + +See man:cargo-init[1] for a similar command which will create a new manifest +in an existing directory. + +== OPTIONS + +=== New Options + +include::options-new.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create a binary Cargo package in the given directory: + + cargo new foo + +== SEE ALSO +man:cargo[1], man:cargo-init[1] diff --git a/src/doc/man/cargo-owner.adoc b/src/doc/man/cargo-owner.adoc deleted file mode 100644 index 63e6e309d..000000000 --- a/src/doc/man/cargo-owner.adoc +++ /dev/null @@ -1,80 +0,0 @@ -= cargo-owner(1) -:idprefix: cargo_owner_ -:doctype: manpage - -== NAME - -cargo-owner - Manage the owners of a crate on the registry - -== SYNOPSIS - -[%hardbreaks] -`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 man:cargo-login[1]. - -If the crate name is not specified, it will use the package name from the -current directory. - -See linkcargo:reference/publishing.html#cargo-owner[the reference] for more -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. - -include::options-token.adoc[] - -include::options-index.adoc[] - -include::options-registry.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. List owners of a package: - - cargo owner --list foo - -. Invite an owner to a package: - - cargo owner --add username foo - -. Remove an owner from a package: - - cargo owner --remove username foo - -== SEE ALSO -man:cargo[1], man:cargo-login[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-owner.md b/src/doc/man/cargo-owner.md new file mode 100644 index 000000000..63e6e309d --- /dev/null +++ b/src/doc/man/cargo-owner.md @@ -0,0 +1,80 @@ += cargo-owner(1) +:idprefix: cargo_owner_ +:doctype: manpage + +== NAME + +cargo-owner - Manage the owners of a crate on the registry + +== SYNOPSIS + +[%hardbreaks] +`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 man:cargo-login[1]. + +If the crate name is not specified, it will use the package name from the +current directory. + +See linkcargo:reference/publishing.html#cargo-owner[the reference] for more +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. + +include::options-token.adoc[] + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. List owners of a package: + + cargo owner --list foo + +. Invite an owner to a package: + + cargo owner --add username foo + +. Remove an owner from a package: + + cargo owner --remove username foo + +== SEE ALSO +man:cargo[1], man:cargo-login[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-package.adoc b/src/doc/man/cargo-package.adoc deleted file mode 100644 index ba1c1b5d6..000000000 --- a/src/doc/man/cargo-package.adoc +++ /dev/null @@ -1,102 +0,0 @@ -= cargo-package(1) -:idprefix: cargo_package_ -:doctype: manpage -:actionverb: Package - -== 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: - -. Load and check the current workspace, performing some basic checks. - - Path dependencies are not allowed unless they have a version key. Cargo - will ignore the path key for dependencies in published packages. - `dev-dependencies` do not have this restriction. -. Create the compressed `.crate` file. - - The original `Cargo.toml` file is rewritten and normalized. - - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the - manifest. - - `Cargo.lock` is automatically included if the package contains an - executable binary or example target. man:cargo-install[1] will use the - packaged lock file if the `--locked` flag is used. - - A `.cargo_vcs_info.json` file is included that contains information - about the current VCS checkout hash if available (not included with - `--allow-dirty`). -. Extract the `.crate` file and build it to verify it can build. - - This will rebuild your package from scratch to ensure that it can be - built from a pristine state. The `--no-verify` flag can be used to skip - this step. -. Check that build scripts did not modify any source files. - -The list of files included can be controlled with the `include` and `exclude` -fields in the manifest. - -See linkcargo:reference/publishing.html[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 - -include::options-target-triple.adoc[] - -include::options-target-dir.adoc[] - -include::options-features.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Create a compressed `.crate` file of the current package: - - cargo package - -== SEE ALSO -man:cargo[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-package.md b/src/doc/man/cargo-package.md new file mode 100644 index 000000000..ba1c1b5d6 --- /dev/null +++ b/src/doc/man/cargo-package.md @@ -0,0 +1,102 @@ += cargo-package(1) +:idprefix: cargo_package_ +:doctype: manpage +:actionverb: Package + +== 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: + +. Load and check the current workspace, performing some basic checks. + - Path dependencies are not allowed unless they have a version key. Cargo + will ignore the path key for dependencies in published packages. + `dev-dependencies` do not have this restriction. +. Create the compressed `.crate` file. + - The original `Cargo.toml` file is rewritten and normalized. + - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the + manifest. + - `Cargo.lock` is automatically included if the package contains an + executable binary or example target. man:cargo-install[1] will use the + packaged lock file if the `--locked` flag is used. + - A `.cargo_vcs_info.json` file is included that contains information + about the current VCS checkout hash if available (not included with + `--allow-dirty`). +. Extract the `.crate` file and build it to verify it can build. + - This will rebuild your package from scratch to ensure that it can be + built from a pristine state. The `--no-verify` flag can be used to skip + this step. +. Check that build scripts did not modify any source files. + +The list of files included can be controlled with the `include` and `exclude` +fields in the manifest. + +See linkcargo:reference/publishing.html[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 + +include::options-target-triple.adoc[] + +include::options-target-dir.adoc[] + +include::options-features.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create a compressed `.crate` file of the current package: + + cargo package + +== SEE ALSO +man:cargo[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-pkgid.adoc b/src/doc/man/cargo-pkgid.adoc deleted file mode 100644 index 98ff9dd9d..000000000 --- a/src/doc/man/cargo-pkgid.adoc +++ /dev/null @@ -1,94 +0,0 @@ -= cargo-pkgid(1) -:idprefix: cargo_pkgid_ -:doctype: manpage - -== 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: - -[%autowidth] -.SPEC Query Format -|=== -|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 - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Retrieve package specification for `foo` package: - - cargo pkgid foo - -. Retrieve package specification for version 1.0.0 of `foo`: - - cargo pkgid foo:1.0.0 - -. Retrieve package specification for `foo` from crates.io: - - cargo pkgid https://github.com/rust-lang/crates.io-index#foo - -== SEE ALSO -man:cargo[1], man:cargo-generate-lockfile[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md new file mode 100644 index 000000000..98ff9dd9d --- /dev/null +++ b/src/doc/man/cargo-pkgid.md @@ -0,0 +1,94 @@ += cargo-pkgid(1) +:idprefix: cargo_pkgid_ +:doctype: manpage + +== 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: + +[%autowidth] +.SPEC Query Format +|=== +|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 + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Retrieve package specification for `foo` package: + + cargo pkgid foo + +. Retrieve package specification for version 1.0.0 of `foo`: + + cargo pkgid foo:1.0.0 + +. Retrieve package specification for `foo` from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +== SEE ALSO +man:cargo[1], man:cargo-generate-lockfile[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-publish.adoc b/src/doc/man/cargo-publish.adoc deleted file mode 100644 index f63c38ba6..000000000 --- a/src/doc/man/cargo-publish.adoc +++ /dev/null @@ -1,90 +0,0 @@ -= cargo-publish(1) -:idprefix: cargo_publish_ -:doctype: manpage -:actionverb: Publish - -== 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 https://crates.io. This performs the -following steps: - -. Performs a few checks, including: - - Checks the `package.publish` key in the manifest for restrictions on which - registries you are allowed to publish to. -. Create a `.crate` file by following the steps in man:cargo-package[1]. -. Upload the crate to the registry. Note that the server will perform - additional checks on the crate. - -This command requires you to be authenticated with either the `--token` option -or using man:cargo-login[1]. - -See linkcargo:reference/publishing.html[the reference] for more details about -packaging and publishing. - -== OPTIONS - -=== Publish Options - -*--dry-run*:: - Perform all checks without uploading. - -include::options-token.adoc[] - -*--no-verify*:: - Don't verify the contents by building them. - -*--allow-dirty*:: - Allow working directories with uncommitted VCS changes to be packaged. - -include::options-index.adoc[] - -include::options-registry.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-target-dir.adoc[] - -include::options-features.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Publish the current package: - - cargo publish - -== SEE ALSO -man:cargo[1], man:cargo-package[1], man:cargo-login[1] diff --git a/src/doc/man/cargo-publish.md b/src/doc/man/cargo-publish.md new file mode 100644 index 000000000..f63c38ba6 --- /dev/null +++ b/src/doc/man/cargo-publish.md @@ -0,0 +1,90 @@ += cargo-publish(1) +:idprefix: cargo_publish_ +:doctype: manpage +:actionverb: Publish + +== 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 https://crates.io. This performs the +following steps: + +. Performs a few checks, including: + - Checks the `package.publish` key in the manifest for restrictions on which + registries you are allowed to publish to. +. Create a `.crate` file by following the steps in man:cargo-package[1]. +. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + +This command requires you to be authenticated with either the `--token` option +or using man:cargo-login[1]. + +See linkcargo:reference/publishing.html[the reference] for more details about +packaging and publishing. + +== OPTIONS + +=== Publish Options + +*--dry-run*:: + Perform all checks without uploading. + +include::options-token.adoc[] + +*--no-verify*:: + Don't verify the contents by building them. + +*--allow-dirty*:: + Allow working directories with uncommitted VCS changes to be packaged. + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-target-dir.adoc[] + +include::options-features.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Publish the current package: + + cargo publish + +== SEE ALSO +man:cargo[1], man:cargo-package[1], man:cargo-login[1] diff --git a/src/doc/man/cargo-run.adoc b/src/doc/man/cargo-run.adoc deleted file mode 100644 index 8aa64e757..000000000 --- a/src/doc/man/cargo-run.adoc +++ /dev/null @@ -1,90 +0,0 @@ -= cargo-run(1) -:idprefix: cargo_run_ -:doctype: manpage -:actionverb: Run - -== 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 - -include::options-package.adoc[] - -=== 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. - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== Display Options - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Build the local package and run its main target (assuming only one binary): - - cargo run - -. Run an example with extra arguments: - - cargo run --example exname -- --exoption exarg1 exarg2 - -== SEE ALSO -man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-run.md b/src/doc/man/cargo-run.md new file mode 100644 index 000000000..8aa64e757 --- /dev/null +++ b/src/doc/man/cargo-run.md @@ -0,0 +1,90 @@ += cargo-run(1) +:idprefix: cargo_run_ +:doctype: manpage +:actionverb: Run + +== 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 + +include::options-package.adoc[] + +=== 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. + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build the local package and run its main target (assuming only one binary): + + cargo run + +. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +== SEE ALSO +man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-rustc.adoc b/src/doc/man/cargo-rustc.adoc deleted file mode 100644 index e3ef3e5fc..000000000 --- a/src/doc/man/cargo-rustc.adoc +++ /dev/null @@ -1,94 +0,0 @@ -= cargo-rustc(1) -:idprefix: cargo_rustc_ -:doctype: manpage -:actionverb: Build - -== 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 https://doc.rust-lang.org/rustc/index.html for documentation on rustc -flags. - -include::description-one-target.adoc[] -To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` -linkcargo:reference/environment-variables.html[environment variable] or the -`build.rustflags` linkcargo:reference/config.html[config value]. - -== OPTIONS - -=== Package Selection - -include::options-package.adoc[] - -=== Target Selection - -When no target selection options are given, `cargo rustc` will build all -binary and library targets of the selected package. - -include::options-targets.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== Display Options - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Check if your package (not including dependencies) uses unsafe code: - - cargo rustc --lib -- -D unsafe-code - -. Try an experimental flag on the nightly compiler, such as this which prints - the size of every type: - - cargo rustc --lib -- -Z print-type-sizes - -== SEE ALSO -man:cargo[1], man:cargo-build[1], man:rustc[1] diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md new file mode 100644 index 000000000..e3ef3e5fc --- /dev/null +++ b/src/doc/man/cargo-rustc.md @@ -0,0 +1,94 @@ += cargo-rustc(1) +:idprefix: cargo_rustc_ +:doctype: manpage +:actionverb: Build + +== 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 https://doc.rust-lang.org/rustc/index.html for documentation on rustc +flags. + +include::description-one-target.adoc[] +To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` +linkcargo:reference/environment-variables.html[environment variable] or the +`build.rustflags` linkcargo:reference/config.html[config value]. + +== OPTIONS + +=== Package Selection + +include::options-package.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo rustc` will build all +binary and library targets of the selected package. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + +. Try an experimental flag on the nightly compiler, such as this which prints + the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + +== SEE ALSO +man:cargo[1], man:cargo-build[1], man:rustc[1] diff --git a/src/doc/man/cargo-rustdoc.adoc b/src/doc/man/cargo-rustdoc.adoc deleted file mode 100644 index 96f37252a..000000000 --- a/src/doc/man/cargo-rustdoc.adoc +++ /dev/null @@ -1,98 +0,0 @@ -= cargo-rustdoc(1) -:idprefix: cargo_rustdoc_ -:doctype: manpage -:actionverb: Document - -== 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 https://doc.rust-lang.org/rustdoc/index.html for documentation on rustdoc -flags. - -include::description-one-target.adoc[] -To pass flags to all rustdoc processes spawned by Cargo, use the -`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable] -or the `build.rustdocflags` linkcargo:reference/config.html[config value]. - -== 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 - -include::options-package.adoc[] - -=== Target Selection - -When no target selection options are given, `cargo rustdoc` will document all -binary and library targets of the selected package. The binary will be skipped -if its name is the same as the lib target. Binaries are skipped if they have -`required-features` that are missing. - -include::options-targets.adoc[] - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== Display Options - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== Miscellaneous Options - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Build documentation with custom CSS included from a given file: - - cargo rustdoc --lib -- --extend-css extra.css - -== SEE ALSO -man:cargo[1], man:cargo-doc[1], man:rustdoc[1] diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md new file mode 100644 index 000000000..96f37252a --- /dev/null +++ b/src/doc/man/cargo-rustdoc.md @@ -0,0 +1,98 @@ += cargo-rustdoc(1) +:idprefix: cargo_rustdoc_ +:doctype: manpage +:actionverb: Document + +== 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 https://doc.rust-lang.org/rustdoc/index.html for documentation on rustdoc +flags. + +include::description-one-target.adoc[] +To pass flags to all rustdoc processes spawned by Cargo, use the +`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable] +or the `build.rustdocflags` linkcargo:reference/config.html[config value]. + +== 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 + +include::options-package.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo rustdoc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +== SEE ALSO +man:cargo[1], man:cargo-doc[1], man:rustdoc[1] diff --git a/src/doc/man/cargo-search.adoc b/src/doc/man/cargo-search.adoc deleted file mode 100644 index 4d5128592..000000000 --- a/src/doc/man/cargo-search.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= cargo-search(1) -:idprefix: cargo_search_ -:doctype: manpage - -== NAME - -cargo-search - Search packages in crates.io - -== SYNOPSIS - -`cargo search [_OPTIONS_] [_QUERY_...]` - -== DESCRIPTION - -This performs a textual search for crates on https://crates.io. The matching -crates will be displayed along with their description in TOML format suitable -for copying into a `Cargo.toml` manifest. - -== OPTIONS - -=== Search Options - -*--limit* _LIMIT_:: - Limit the number of results (default: 10, max: 100). - -include::options-index.adoc[] - -include::options-registry.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Search for a package from crates.io: - - cargo search serde - -== SEE ALSO -man:cargo[1], man:cargo-install[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-search.md b/src/doc/man/cargo-search.md new file mode 100644 index 000000000..4d5128592 --- /dev/null +++ b/src/doc/man/cargo-search.md @@ -0,0 +1,49 @@ += cargo-search(1) +:idprefix: cargo_search_ +:doctype: manpage + +== NAME + +cargo-search - Search packages in crates.io + +== SYNOPSIS + +`cargo search [_OPTIONS_] [_QUERY_...]` + +== DESCRIPTION + +This performs a textual search for crates on https://crates.io. The matching +crates will be displayed along with their description in TOML format suitable +for copying into a `Cargo.toml` manifest. + +== OPTIONS + +=== Search Options + +*--limit* _LIMIT_:: + Limit the number of results (default: 10, max: 100). + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Search for a package from crates.io: + + cargo search serde + +== SEE ALSO +man:cargo[1], man:cargo-install[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-test.adoc b/src/doc/man/cargo-test.adoc deleted file mode 100644 index ba338b12b..000000000 --- a/src/doc/man/cargo-test.adoc +++ /dev/null @@ -1,166 +0,0 @@ -= cargo-test(1) -:idprefix: cargo_test_ -:doctype: manpage -:actionverb: Test -:nouns: tests - -== 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 -link:https://doc.rust-lang.org/rustdoc/[rustdoc book] for more information on -writing doc tests. - -== OPTIONS - -=== Test Options - -include::options-test.adoc[] - -=== Package Selection - -include::options-packages.adoc[] - -=== 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_` -linkcargo:reference/environment-variables.html#environment-variables-cargo-sets-for-crates[environment variable] -is set when the integration test is built so that it can use the -link:https://doc.rust-lang.org/std/macro.env.html[`env` macro] to locate the -executable. - -include::options-targets.adoc[] - -*--doc*:: - Test only the library's documentation. This cannot be mixed with other - target options. - -include::options-features.adoc[] - -=== Compilation Options - -include::options-target-triple.adoc[] - -include::options-release.adoc[] - -=== Output Options - -include::options-target-dir.adoc[] - -=== 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 - -include::options-display.adoc[] - -include::options-message-format.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -=== 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 - -include::options-jobs.adoc[] - -include::section-profiles.adoc[] - -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. - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Execute all the unit and integration tests of the current package: - - cargo test - -. Run only tests whose names match against a filter string: - - cargo test name_filter - -. Run only a specific test within a specific integration test: - - cargo test --test int_test_name -- modname::test_name - -== SEE ALSO -man:cargo[1], man:cargo-bench[1] diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md new file mode 100644 index 000000000..ba338b12b --- /dev/null +++ b/src/doc/man/cargo-test.md @@ -0,0 +1,166 @@ += cargo-test(1) +:idprefix: cargo_test_ +:doctype: manpage +:actionverb: Test +:nouns: tests + +== 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 +link:https://doc.rust-lang.org/rustdoc/[rustdoc book] for more information on +writing doc tests. + +== OPTIONS + +=== Test Options + +include::options-test.adoc[] + +=== Package Selection + +include::options-packages.adoc[] + +=== 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_` +linkcargo:reference/environment-variables.html#environment-variables-cargo-sets-for-crates[environment variable] +is set when the integration test is built so that it can use the +link:https://doc.rust-lang.org/std/macro.env.html[`env` macro] to locate the +executable. + +include::options-targets.adoc[] + +*--doc*:: + Test only the library's documentation. This cannot be mixed with other + target options. + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== 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 + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== 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 + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +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. + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Execute all the unit and integration tests of the current package: + + cargo test + +. Run only tests whose names match against a filter string: + + cargo test name_filter + +. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +== SEE ALSO +man:cargo[1], man:cargo-bench[1] diff --git a/src/doc/man/cargo-tree.adoc b/src/doc/man/cargo-tree.adoc deleted file mode 100644 index 86b3276a4..000000000 --- a/src/doc/man/cargo-tree.adoc +++ /dev/null @@ -1,227 +0,0 @@ -= cargo-tree(1) -:idprefix: cargo_tree_ -:doctype: manpage -:actionverb: Display -:noall: true - -== 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 - -include::options-packages.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-features.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::options-locked.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Display the tree for the package in the current directory: - - cargo tree - -. Display all the packages that depend on the `syn` package: - - cargo tree -i syn - -. Show the features enabled on each package: - - cargo tree --format "{p} {f}" - -. 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 - -. Explain why features are enabled for the `syn` package: - - cargo tree -e features -i syn -+ -The `-e features` flag is used to show features. The `-i` flag is used to -invert the graph so that it displays the packages that depend on `syn`. An -example of what this would display: -+ ----- -syn v1.0.17 -├── syn feature "clone-impls" -│ └── syn feature "default" -│ └── rustversion v1.0.2 -│ └── rustversion feature "default" -│ └── myproject v0.1.0 (/myproject) -│ └── myproject feature "default" (command-line) -├── syn feature "default" (*) -├── syn feature "derive" -│ └── syn feature "default" (*) -├── syn feature "full" -│ └── rustversion v1.0.2 (*) -├── syn feature "parsing" -│ └── syn feature "default" (*) -├── syn feature "printing" -│ └── syn feature "default" (*) -├── syn feature "proc-macro" -│ └── syn feature "default" (*) -└── syn feature "quote" - ├── syn feature "printing" (*) - └── syn feature "proc-macro" (*) ----- -+ -To read this graph, you can follow the chain for each feature from the root to -see why it is included. For example, the "full" feature is added by the -`rustversion` crate which is included from `myproject` (with the default -features), and `myproject` is the package selected on the command-line. All -of the other `syn` features are added by the "default" feature ("quote" is -added by "printing" and "proc-macro", both of which are default features). -+ -If you're having difficulty cross-referencing the de-duplicated `(*)` entries, -try with the `--no-dedupe` flag to get the full output. - -== SEE ALSO -man:cargo[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-tree.md b/src/doc/man/cargo-tree.md new file mode 100644 index 000000000..86b3276a4 --- /dev/null +++ b/src/doc/man/cargo-tree.md @@ -0,0 +1,227 @@ += cargo-tree(1) +:idprefix: cargo_tree_ +:doctype: manpage +:actionverb: Display +:noall: true + +== 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 + +include::options-packages.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-features.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::options-locked.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Display the tree for the package in the current directory: + + cargo tree + +. Display all the packages that depend on the `syn` package: + + cargo tree -i syn + +. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + +. 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 + +. Explain why features are enabled for the `syn` package: + + cargo tree -e features -i syn ++ +The `-e features` flag is used to show features. The `-i` flag is used to +invert the graph so that it displays the packages that depend on `syn`. An +example of what this would display: ++ +---- +syn v1.0.17 +├── syn feature "clone-impls" +│ └── syn feature "default" +│ └── rustversion v1.0.2 +│ └── rustversion feature "default" +│ └── myproject v0.1.0 (/myproject) +│ └── myproject feature "default" (command-line) +├── syn feature "default" (*) +├── syn feature "derive" +│ └── syn feature "default" (*) +├── syn feature "full" +│ └── rustversion v1.0.2 (*) +├── syn feature "parsing" +│ └── syn feature "default" (*) +├── syn feature "printing" +│ └── syn feature "default" (*) +├── syn feature "proc-macro" +│ └── syn feature "default" (*) +└── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) +---- ++ +To read this graph, you can follow the chain for each feature from the root to +see why it is included. For example, the "full" feature is added by the +`rustversion` crate which is included from `myproject` (with the default +features), and `myproject` is the package selected on the command-line. All +of the other `syn` features are added by the "default" feature ("quote" is +added by "printing" and "proc-macro", both of which are default features). ++ +If you're having difficulty cross-referencing the de-duplicated `(*)` entries, +try with the `--no-dedupe` flag to get the full output. + +== SEE ALSO +man:cargo[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-uninstall.adoc b/src/doc/man/cargo-uninstall.adoc deleted file mode 100644 index b75a10401..000000000 --- a/src/doc/man/cargo-uninstall.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= cargo-uninstall(1) -:idprefix: cargo_uninstall_ -:doctype: manpage - -== NAME - -cargo-uninstall - Remove a Rust binary - -== SYNOPSIS - -`cargo uninstall [_OPTIONS_] [_SPEC_...]` - -== DESCRIPTION - -This command removes a package installed with man:cargo-install[1]. The _SPEC_ -argument is a package ID specification of the package to remove (see -man:cargo-pkgid[1]). - -By default all binaries are removed for a crate but the `--bin` and -`--example` flags can be used to only remove particular binaries. - -include::description-install-root.adoc[] - -== 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 - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Uninstall a previously installed package. - - cargo uninstall ripgrep - -== SEE ALSO -man:cargo[1], man:cargo-install[1] diff --git a/src/doc/man/cargo-uninstall.md b/src/doc/man/cargo-uninstall.md new file mode 100644 index 000000000..b75a10401 --- /dev/null +++ b/src/doc/man/cargo-uninstall.md @@ -0,0 +1,57 @@ += cargo-uninstall(1) +:idprefix: cargo_uninstall_ +:doctype: manpage + +== NAME + +cargo-uninstall - Remove a Rust binary + +== SYNOPSIS + +`cargo uninstall [_OPTIONS_] [_SPEC_...]` + +== DESCRIPTION + +This command removes a package installed with man:cargo-install[1]. The _SPEC_ +argument is a package ID specification of the package to remove (see +man:cargo-pkgid[1]). + +By default all binaries are removed for a crate but the `--bin` and +`--example` flags can be used to only remove particular binaries. + +include::description-install-root.adoc[] + +== 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 + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Uninstall a previously installed package. + + cargo uninstall ripgrep + +== SEE ALSO +man:cargo[1], man:cargo-install[1] diff --git a/src/doc/man/cargo-update.adoc b/src/doc/man/cargo-update.adoc deleted file mode 100644 index c8a527435..000000000 --- a/src/doc/man/cargo-update.adoc +++ /dev/null @@ -1,81 +0,0 @@ -= cargo-update(1) -:idprefix: cargo_update_ -:doctype: manpage - -== 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 man:cargo-build[1] or man:cargo-generate-lockfile[1]. - -== OPTIONS - -=== Update Options - -*-p* _SPEC_...:: -*--package* _SPEC_...:: - Update only the specified packages. This flag may be specified - multiple times. See man:cargo-pkgid[1] for the SPEC format. -+ -If packages are specified with the `-p` flag, then a conservative update of -the lockfile will be performed. This means that only the dependency specified -by SPEC will be updated. Its transitive dependencies will be updated only if -SPEC cannot be updated without updating dependencies. All other dependencies -will remain locked at their currently recorded versions. -+ -If `-p` is not specified, all dependencies are updated. - -*--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 - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Update all dependencies in the lockfile: - - cargo update - -. Update only specific dependencies: - - cargo update -p foo -p bar - -. Set a specific dependency to a specific version: - - cargo update -p foo --precise 1.2.3 - -== SEE ALSO -man:cargo[1], man:cargo-generate-lockfile[1] diff --git a/src/doc/man/cargo-update.md b/src/doc/man/cargo-update.md new file mode 100644 index 000000000..c8a527435 --- /dev/null +++ b/src/doc/man/cargo-update.md @@ -0,0 +1,81 @@ += cargo-update(1) +:idprefix: cargo_update_ +:doctype: manpage + +== 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 man:cargo-build[1] or man:cargo-generate-lockfile[1]. + +== OPTIONS + +=== Update Options + +*-p* _SPEC_...:: +*--package* _SPEC_...:: + Update only the specified packages. This flag may be specified + multiple times. See man:cargo-pkgid[1] for the SPEC format. ++ +If packages are specified with the `-p` flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions. ++ +If `-p` is not specified, all dependencies are updated. + +*--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 + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Update all dependencies in the lockfile: + + cargo update + +. Update only specific dependencies: + + cargo update -p foo -p bar + +. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +== SEE ALSO +man:cargo[1], man:cargo-generate-lockfile[1] diff --git a/src/doc/man/cargo-vendor.adoc b/src/doc/man/cargo-vendor.adoc deleted file mode 100644 index d1d3fc3bb..000000000 --- a/src/doc/man/cargo-vendor.adoc +++ /dev/null @@ -1,82 +0,0 @@ -= cargo-vendor(1) -:idprefix: cargo_vendor_ -:doctype: manpage - -== 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 - -include::options-manifest-path.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::options-locked.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Vendor all dependencies into a local "vendor" folder - - cargo vendor - -. Vendor all dependencies into a local "third-party/vendor" folder - - cargo vendor third-party/vendor - -. Vendor the current workspace as well as another to "vendor" - - cargo vendor -s ../path/to/Cargo.toml - -== SEE ALSO -man:cargo[1] - diff --git a/src/doc/man/cargo-vendor.md b/src/doc/man/cargo-vendor.md new file mode 100644 index 000000000..d1d3fc3bb --- /dev/null +++ b/src/doc/man/cargo-vendor.md @@ -0,0 +1,82 @@ += cargo-vendor(1) +:idprefix: cargo_vendor_ +:doctype: manpage + +== 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 + +include::options-manifest-path.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::options-locked.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Vendor all dependencies into a local "vendor" folder + + cargo vendor + +. Vendor all dependencies into a local "third-party/vendor" folder + + cargo vendor third-party/vendor + +. Vendor the current workspace as well as another to "vendor" + + cargo vendor -s ../path/to/Cargo.toml + +== SEE ALSO +man:cargo[1] + diff --git a/src/doc/man/cargo-verify-project.adoc b/src/doc/man/cargo-verify-project.adoc deleted file mode 100644 index 7b963f8c5..000000000 --- a/src/doc/man/cargo-verify-project.adoc +++ /dev/null @@ -1,57 +0,0 @@ -= cargo-verify-project(1) -:idprefix: cargo_verify-project_ -:doctype: manpage - -== 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 - -include::options-display.adoc[] - -=== Manifest Options - -include::options-manifest-path.adoc[] - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -== Exit Status - -0:: - The workspace is OK. - -1:: - The workspace is invalid. - -== EXAMPLES - -. Check the current workspace for errors: - - cargo verify-project - -== SEE ALSO -man:cargo[1], man:cargo-package[1] diff --git a/src/doc/man/cargo-verify-project.md b/src/doc/man/cargo-verify-project.md new file mode 100644 index 000000000..7b963f8c5 --- /dev/null +++ b/src/doc/man/cargo-verify-project.md @@ -0,0 +1,57 @@ += cargo-verify-project(1) +:idprefix: cargo_verify-project_ +:doctype: manpage + +== 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 + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +== Exit Status + +0:: + The workspace is OK. + +1:: + The workspace is invalid. + +== EXAMPLES + +. Check the current workspace for errors: + + cargo verify-project + +== SEE ALSO +man:cargo[1], man:cargo-package[1] diff --git a/src/doc/man/cargo-version.adoc b/src/doc/man/cargo-version.adoc deleted file mode 100644 index 4c3bb7a1b..000000000 --- a/src/doc/man/cargo-version.adoc +++ /dev/null @@ -1,39 +0,0 @@ -= cargo-version(1) -:idprefix: cargo_version_ -:doctype: manpage - -== NAME - -cargo-version - Show version information - -== SYNOPSIS - -`cargo version [_OPTIONS_]` - -== DESCRIPTION - -Displays the version of Cargo. - -== OPTIONS - -*-v*:: -*--verbose*:: - Display additional version information. - -== EXAMPLES - -. Display the version: - - cargo version - -. The version is also available via flags: - - cargo --version - cargo -V - -. Display extra version information: - - cargo -Vv - -== SEE ALSO -man:cargo[1] diff --git a/src/doc/man/cargo-version.md b/src/doc/man/cargo-version.md new file mode 100644 index 000000000..4c3bb7a1b --- /dev/null +++ b/src/doc/man/cargo-version.md @@ -0,0 +1,39 @@ += cargo-version(1) +:idprefix: cargo_version_ +:doctype: manpage + +== NAME + +cargo-version - Show version information + +== SYNOPSIS + +`cargo version [_OPTIONS_]` + +== DESCRIPTION + +Displays the version of Cargo. + +== OPTIONS + +*-v*:: +*--verbose*:: + Display additional version information. + +== EXAMPLES + +. Display the version: + + cargo version + +. The version is also available via flags: + + cargo --version + cargo -V + +. Display extra version information: + + cargo -Vv + +== SEE ALSO +man:cargo[1] diff --git a/src/doc/man/cargo-yank.adoc b/src/doc/man/cargo-yank.adoc deleted file mode 100644 index a08c71777..000000000 --- a/src/doc/man/cargo-yank.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= cargo-yank(1) -:idprefix: cargo_yank_ -:doctype: manpage - -== 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 man: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. - -include::options-token.adoc[] - -include::options-index.adoc[] - -include::options-registry.adoc[] - -=== Display Options - -include::options-display.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== EXAMPLES - -. Yank a crate from the index: - - cargo yank --vers 1.0.7 foo - -== SEE ALSO -man:cargo[1], man:cargo-login[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-yank.md b/src/doc/man/cargo-yank.md new file mode 100644 index 000000000..a08c71777 --- /dev/null +++ b/src/doc/man/cargo-yank.md @@ -0,0 +1,64 @@ += cargo-yank(1) +:idprefix: cargo_yank_ +:doctype: manpage + +== 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 man: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. + +include::options-token.adoc[] + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Yank a crate from the index: + + cargo yank --vers 1.0.7 foo + +== SEE ALSO +man:cargo[1], man:cargo-login[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo.adoc b/src/doc/man/cargo.adoc deleted file mode 100644 index 59c7b1fcc..000000000 --- a/src/doc/man/cargo.adoc +++ /dev/null @@ -1,226 +0,0 @@ -= cargo(1) -:doctype: manpage - -== NAME - -cargo - The Rust package manager - -== SYNOPSIS - -[%hardbreaks] -`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 - -man:cargo-bench[1]:: - Execute benchmarks of a package. - -man:cargo-build[1]:: - Compile a package. - -man:cargo-check[1]:: - Check a local package and all of its dependencies for errors. - -man:cargo-clean[1]:: - Remove artifacts that Cargo has generated in the past. - -man:cargo-doc[1]:: - Build a package's documentation. - -man:cargo-fetch[1]:: - Fetch dependencies of a package from the network. - -man:cargo-fix[1]:: - Automatically fix lint warnings reported by rustc. - -man:cargo-run[1]:: - Run a binary or example of the local package. - -man:cargo-rustc[1]:: - Compile a package, and pass extra options to the compiler. - -man:cargo-rustdoc[1]:: - Build a package's documentation, using specified custom flags. - -man:cargo-test[1]:: - Execute unit and integration tests of a package. - -=== Manifest Commands - -man:cargo-generate-lockfile[1]:: - Generate `Cargo.lock` for a project. - -man:cargo-locate-project[1]:: - Print a JSON representation of a `Cargo.toml` file's location. - -man:cargo-metadata[1]:: - Output the resolved dependencies of a package, the concrete used versions - including overrides, in machine-readable format. - -man:cargo-pkgid[1]:: - Print a fully qualified package specification. - -man:cargo-tree[1]:: - Display a tree visualization of a dependency graph. - -man:cargo-update[1]:: - Update dependencies as recorded in the local lock file. - -man:cargo-vendor[1]:: - Vendor all dependencies locally. - -man:cargo-verify-project[1]:: - Check correctness of crate manifest. - -=== Package Commands - -man:cargo-init[1]:: - Create a new Cargo package in an existing directory. - -man:cargo-install[1]:: - Build and install a Rust binary. - -man:cargo-new[1]:: - Create a new Cargo package. - -man:cargo-search[1]:: - Search packages in crates.io. - -man:cargo-uninstall[1]:: - Remove a Rust binary. - -=== Publishing Commands - -man:cargo-login[1]:: - Save an API token from the registry locally. - -man:cargo-owner[1]:: - Manage the owners of a crate on the registry. - -man:cargo-package[1]:: - Assemble the local package into a distributable tarball. - -man:cargo-publish[1]:: - Upload a package to the registry. - -man:cargo-yank[1]:: - Remove a pushed crate from the index. - -=== General Commands - -man:cargo-help[1]:: - Display help information about Cargo. - -man: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 - -include::options-display.adoc[] - -=== Manifest Options - -include::options-locked.adoc[] - -=== Common Options - -include::options-common.adoc[] - -include::section-environment.adoc[] - -include::section-exit-status.adoc[] - -== 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 man: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 linkcargo:reference/config.html[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 - -. Build a local package and all of its dependencies: - - cargo build - -. Build a package with optimizations: - - cargo build --release - -. Run tests for a cross-compiled target: - - cargo test --target i686-unknown-linux-gnu - -. Create a new package that builds an executable: - - cargo new foobar - -. Create a package in the current directory: - - mkdir foo && cd foo - cargo init . - -. Learn about a command's options and usage: - - cargo help clean - -== BUGS - -See https://github.com/rust-lang/cargo/issues for issues. - -== SEE ALSO -man:rustc[1], man:rustdoc[1] diff --git a/src/doc/man/cargo.md b/src/doc/man/cargo.md new file mode 100644 index 000000000..59c7b1fcc --- /dev/null +++ b/src/doc/man/cargo.md @@ -0,0 +1,226 @@ += cargo(1) +:doctype: manpage + +== NAME + +cargo - The Rust package manager + +== SYNOPSIS + +[%hardbreaks] +`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 + +man:cargo-bench[1]:: + Execute benchmarks of a package. + +man:cargo-build[1]:: + Compile a package. + +man:cargo-check[1]:: + Check a local package and all of its dependencies for errors. + +man:cargo-clean[1]:: + Remove artifacts that Cargo has generated in the past. + +man:cargo-doc[1]:: + Build a package's documentation. + +man:cargo-fetch[1]:: + Fetch dependencies of a package from the network. + +man:cargo-fix[1]:: + Automatically fix lint warnings reported by rustc. + +man:cargo-run[1]:: + Run a binary or example of the local package. + +man:cargo-rustc[1]:: + Compile a package, and pass extra options to the compiler. + +man:cargo-rustdoc[1]:: + Build a package's documentation, using specified custom flags. + +man:cargo-test[1]:: + Execute unit and integration tests of a package. + +=== Manifest Commands + +man:cargo-generate-lockfile[1]:: + Generate `Cargo.lock` for a project. + +man:cargo-locate-project[1]:: + Print a JSON representation of a `Cargo.toml` file's location. + +man:cargo-metadata[1]:: + Output the resolved dependencies of a package, the concrete used versions + including overrides, in machine-readable format. + +man:cargo-pkgid[1]:: + Print a fully qualified package specification. + +man:cargo-tree[1]:: + Display a tree visualization of a dependency graph. + +man:cargo-update[1]:: + Update dependencies as recorded in the local lock file. + +man:cargo-vendor[1]:: + Vendor all dependencies locally. + +man:cargo-verify-project[1]:: + Check correctness of crate manifest. + +=== Package Commands + +man:cargo-init[1]:: + Create a new Cargo package in an existing directory. + +man:cargo-install[1]:: + Build and install a Rust binary. + +man:cargo-new[1]:: + Create a new Cargo package. + +man:cargo-search[1]:: + Search packages in crates.io. + +man:cargo-uninstall[1]:: + Remove a Rust binary. + +=== Publishing Commands + +man:cargo-login[1]:: + Save an API token from the registry locally. + +man:cargo-owner[1]:: + Manage the owners of a crate on the registry. + +man:cargo-package[1]:: + Assemble the local package into a distributable tarball. + +man:cargo-publish[1]:: + Upload a package to the registry. + +man:cargo-yank[1]:: + Remove a pushed crate from the index. + +=== General Commands + +man:cargo-help[1]:: + Display help information about Cargo. + +man: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 + +include::options-display.adoc[] + +=== Manifest Options + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== 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 man: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 linkcargo:reference/config.html[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 + +. Build a local package and all of its dependencies: + + cargo build + +. Build a package with optimizations: + + cargo build --release + +. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + +. Create a new package that builds an executable: + + cargo new foobar + +. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + +. Learn about a command's options and usage: + + cargo help clean + +== BUGS + +See https://github.com/rust-lang/cargo/issues for issues. + +== SEE ALSO +man:rustc[1], man:rustdoc[1] diff --git a/src/doc/man/description-install-root.adoc b/src/doc/man/description-install-root.adoc deleted file mode 100644 index d7773d3b2..000000000 --- a/src/doc/man/description-install-root.adoc +++ /dev/null @@ -1,7 +0,0 @@ -The installation root is determined, in order of precedence: - -- `--root` option -- `CARGO_INSTALL_ROOT` environment variable -- `install.root` Cargo linkcargo:reference/config.html[config value] -- `CARGO_HOME` environment variable -- `$HOME/.cargo` diff --git a/src/doc/man/description-new-authors.adoc b/src/doc/man/description-new-authors.adoc deleted file mode 100644 index 0435295b7..000000000 --- a/src/doc/man/description-new-authors.adoc +++ /dev/null @@ -1,24 +0,0 @@ -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 linkcargo:reference/config.html[the reference] for more information about -configuration files. diff --git a/src/doc/man/description-one-target.adoc b/src/doc/man/description-one-target.adoc deleted file mode 100644 index 7af18131f..000000000 --- a/src/doc/man/description-one-target.adoc +++ /dev/null @@ -1,4 +0,0 @@ -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. diff --git a/src/doc/man/includes/description-install-root.md b/src/doc/man/includes/description-install-root.md new file mode 100644 index 000000000..d7773d3b2 --- /dev/null +++ b/src/doc/man/includes/description-install-root.md @@ -0,0 +1,7 @@ +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo linkcargo:reference/config.html[config value] +- `CARGO_HOME` environment variable +- `$HOME/.cargo` diff --git a/src/doc/man/includes/description-new-authors.md b/src/doc/man/includes/description-new-authors.md new file mode 100644 index 000000000..0435295b7 --- /dev/null +++ b/src/doc/man/includes/description-new-authors.md @@ -0,0 +1,24 @@ +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 linkcargo:reference/config.html[the reference] for more information about +configuration files. diff --git a/src/doc/man/includes/description-one-target.md b/src/doc/man/includes/description-one-target.md new file mode 100644 index 000000000..7af18131f --- /dev/null +++ b/src/doc/man/includes/description-one-target.md @@ -0,0 +1,4 @@ +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. diff --git a/src/doc/man/includes/options-display.md b/src/doc/man/includes/options-display.md new file mode 100644 index 000000000..cc2e22633 --- /dev/null +++ b/src/doc/man/includes/options-display.md @@ -0,0 +1,22 @@ +*-v*:: +*--verbose*:: + Use verbose output. May be specified twice for "very verbose" output which + includes extra output such as dependency warnings and build script output. + May also be specified with the `term.verbose` + linkcargo:reference/config.html[config value]. + +*-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` +linkcargo:reference/config.html[config value]. diff --git a/src/doc/man/includes/options-index.md b/src/doc/man/includes/options-index.md new file mode 100644 index 000000000..1321866ba --- /dev/null +++ b/src/doc/man/includes/options-index.md @@ -0,0 +1,2 @@ +*--index* _INDEX_:: + The URL of the registry index to use. diff --git a/src/doc/man/includes/options-jobs.md b/src/doc/man/includes/options-jobs.md new file mode 100644 index 000000000..9d817426b --- /dev/null +++ b/src/doc/man/includes/options-jobs.md @@ -0,0 +1,5 @@ +*-j* _N_:: +*--jobs* _N_:: + Number of parallel jobs to run. May also be specified with the + `build.jobs` linkcargo:reference/config.html[config value]. Defaults to + the number of CPUs. diff --git a/src/doc/man/includes/options-locked.md b/src/doc/man/includes/options-locked.md new file mode 100644 index 000000000..45bbfa511 --- /dev/null +++ b/src/doc/man/includes/options-locked.md @@ -0,0 +1,24 @@ +*--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 man:cargo-fetch[1] command to download dependencies before going +offline. ++ +May also be specified with the `net.offline` linkcargo:reference/config.html[config value]. diff --git a/src/doc/man/includes/options-manifest-path.md b/src/doc/man/includes/options-manifest-path.md new file mode 100644 index 000000000..79a2394a6 --- /dev/null +++ b/src/doc/man/includes/options-manifest-path.md @@ -0,0 +1,3 @@ +*--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. diff --git a/src/doc/man/includes/options-message-format.md b/src/doc/man/includes/options-message-format.md new file mode 100644 index 000000000..818d78f81 --- /dev/null +++ b/src/doc/man/includes/options-message-format.md @@ -0,0 +1,18 @@ +*--message-format* _FMT_:: + The output format for diagnostic messages. Can be specified multiple times + and consists of comma-separated values. Valid values: ++ +- `human` (default): Display in a human-readable text format. +- `short`: Emit shorter, human-readable text messages. +- `json`: Emit JSON messages to stdout. See + linkcargo:reference/external-tools.html#json-messages[the reference] + 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. diff --git a/src/doc/man/includes/options-new.md b/src/doc/man/includes/options-new.md new file mode 100644 index 000000000..2218599ae --- /dev/null +++ b/src/doc/man/includes/options-new.md @@ -0,0 +1,29 @@ +*--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 linkcargo:reference/config.html[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. diff --git a/src/doc/man/includes/options-profile.md b/src/doc/man/includes/options-profile.md new file mode 100644 index 000000000..3c5ad14c7 --- /dev/null +++ b/src/doc/man/includes/options-profile.md @@ -0,0 +1,6 @@ +*--profile* _NAME_:: + Changes convert:lowercase[{actionverb}] behavior. Currently only `test` is + supported, which will convert:lowercase[{actionverb}] with the + `#[cfg(test)]` attribute enabled. This is useful to have it + convert:lowercase[{actionverb}] unit tests which are usually excluded via + the `cfg` attribute. This does not change the actual profile used. diff --git a/src/doc/man/includes/options-registry.md b/src/doc/man/includes/options-registry.md new file mode 100644 index 000000000..a0c4c27c8 --- /dev/null +++ b/src/doc/man/includes/options-registry.md @@ -0,0 +1,4 @@ +*--registry* _REGISTRY_:: + Name of the registry to use. Registry names are defined in linkcargo:reference/config.html[Cargo config files]. + If not specified, the default registry is used, which is defined by the + `registry.default` config key which defaults to `crates-io`. diff --git a/src/doc/man/includes/options-release.md b/src/doc/man/includes/options-release.md new file mode 100644 index 000000000..e99539172 --- /dev/null +++ b/src/doc/man/includes/options-release.md @@ -0,0 +1,3 @@ +*--release*:: + {actionverb} optimized artifacts with the `release` profile. See the + <> section for details on how this affects profile selection. diff --git a/src/doc/man/includes/options-target-dir.md b/src/doc/man/includes/options-target-dir.md new file mode 100644 index 000000000..f044bd712 --- /dev/null +++ b/src/doc/man/includes/options-target-dir.md @@ -0,0 +1,5 @@ +*--target-dir* _DIRECTORY_:: + Directory for all generated artifacts and intermediate files. May also be + specified with the `CARGO_TARGET_DIR` environment variable, or the + `build.target-dir` linkcargo:reference/config.html[config value]. Defaults + to `target` in the root of the workspace. diff --git a/src/doc/man/includes/options-target-triple.md b/src/doc/man/includes/options-target-triple.md new file mode 100644 index 000000000..9cb6d7c85 --- /dev/null +++ b/src/doc/man/includes/options-target-triple.md @@ -0,0 +1,12 @@ +*--target* _TRIPLE_:: + {actionverb} 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` +linkcargo:reference/config.html[config value]. ++ +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +linkcargo:guide/build-cache.html[build cache] documentation for more details. diff --git a/src/doc/man/includes/options-targets-lib-bin.md b/src/doc/man/includes/options-targets-lib-bin.md new file mode 100644 index 000000000..8668ba84b --- /dev/null +++ b/src/doc/man/includes/options-targets-lib-bin.md @@ -0,0 +1,8 @@ +*--lib*:: + {actionverb} the package's library. + +*--bin* _NAME_...:: + {actionverb} the specified binary. This flag may be specified multiple times. + +*--bins*:: + {actionverb} all binary targets. diff --git a/src/doc/man/includes/options-targets.md b/src/doc/man/includes/options-targets.md new file mode 100644 index 000000000..6a8a46cd7 --- /dev/null +++ b/src/doc/man/includes/options-targets.md @@ -0,0 +1,39 @@ +Passing target selection flags will convert:lowercase[{actionverb}] only the +specified targets. + +include::options-targets-lib-bin.adoc[] + +*--example* _NAME_...:: + {actionverb} the specified example. This flag may be specified multiple times. + +*--examples*:: + {actionverb} all example targets. + +*--test* _NAME_...:: + {actionverb} the specified integration test. This flag may be specified multiple + times. + +*--tests*:: + {actionverb} all targets in test mode that have the `test = true` manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build any + required dependencies, so the lib target may be built twice (once as a + unittest, and once as a dependency for binaries, integration tests, etc.). + Targets may be enabled or disabled by setting the `test` flag in the + manifest settings for the target. + +*--bench* _NAME_...:: + {actionverb} the specified benchmark. This flag may be specified multiple times. + +*--benches*:: + {actionverb} all targets in benchmark mode that have the `bench = true` + manifest flag set. By default this includes the library and binaries built + as benchmarks, and bench targets. Be aware that this will also build any + required dependencies, so the lib target may be built twice (once as a + benchmark, and once as a dependency for binaries, benchmarks, etc.). + Targets may be enabled or disabled by setting the `bench` flag in the + manifest settings for the target. + +*--all-targets*:: + {actionverb} all targets. This is equivalent to specifying `--lib --bins + --tests --benches --examples`. diff --git a/src/doc/man/includes/options-test.md b/src/doc/man/includes/options-test.md new file mode 100644 index 000000000..0cdcb3d7e --- /dev/null +++ b/src/doc/man/includes/options-test.md @@ -0,0 +1,8 @@ +*--no-run*:: + Compile, but don't run {nouns}. + +*--no-fail-fast*:: + Run all {nouns} regardless of failure. Without this flag, Cargo will exit + after the first executable fails. The Rust test harness will run all + {nouns} within the executable to completion, this flag only applies to + the executable as a whole. diff --git a/src/doc/man/includes/options-token.md b/src/doc/man/includes/options-token.md new file mode 100644 index 000000000..5f25ffbf2 --- /dev/null +++ b/src/doc/man/includes/options-token.md @@ -0,0 +1,10 @@ +*--token* _TOKEN_:: + API token to use when authenticating. This overrides the token stored in + the credentials file (which is created by man:cargo-login[1]). ++ +linkcargo:reference/config.html[Cargo config] environment variables can be +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. diff --git a/src/doc/man/includes/section-environment.md b/src/doc/man/includes/section-environment.md new file mode 100644 index 000000000..5cc69e995 --- /dev/null +++ b/src/doc/man/includes/section-environment.md @@ -0,0 +1,4 @@ +== ENVIRONMENT + +See linkcargo:reference/environment-variables.html[the reference] for +details on environment variables that Cargo reads. diff --git a/src/doc/man/includes/section-exit-status.md b/src/doc/man/includes/section-exit-status.md new file mode 100644 index 000000000..427b3903c --- /dev/null +++ b/src/doc/man/includes/section-exit-status.md @@ -0,0 +1,7 @@ +== Exit Status + +0:: + Cargo succeeded. + +101:: + Cargo failed to complete. diff --git a/src/doc/man/includes/section-features.md b/src/doc/man/includes/section-features.md new file mode 100644 index 000000000..2161ad967 --- /dev/null +++ b/src/doc/man/includes/section-features.md @@ -0,0 +1,23 @@ +=== 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. diff --git a/src/doc/man/includes/section-options-common.md b/src/doc/man/includes/section-options-common.md new file mode 100644 index 000000000..aa0e24f52 --- /dev/null +++ b/src/doc/man/includes/section-options-common.md @@ -0,0 +1,14 @@ +*+TOOLCHAIN*:: + If Cargo has been installed with rustup, and the first argument to `cargo` + begins with `+`, it will be interpreted as a rustup toolchain name (such + as `+stable` or `+nightly`). + See the link:https://github.com/rust-lang/rustup/[rustup documentation] + for more information about how toolchain overrides work. + +*-h*:: +*--help*:: + Prints help information. + +*-Z* _FLAG_...:: + Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for + details. diff --git a/src/doc/man/includes/section-options-package.md b/src/doc/man/includes/section-options-package.md new file mode 100644 index 000000000..c0cfbc35e --- /dev/null +++ b/src/doc/man/includes/section-options-package.md @@ -0,0 +1,7 @@ +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +*-p* _SPEC_:: +*--package* _SPEC_:: + The package to convert:lowercase[{actionverb}]. See man:cargo-pkgid[1] for + the SPEC format. diff --git a/src/doc/man/includes/section-package-selection.md b/src/doc/man/includes/section-package-selection.md new file mode 100644 index 000000000..dbddfb9c0 --- /dev/null +++ b/src/doc/man/includes/section-package-selection.md @@ -0,0 +1,27 @@ +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_...:: + {actionverb} only the specified packages. See man:cargo-pkgid[1] for the + SPEC format. This flag may be specified multiple times. + +*--workspace*:: + {actionverb} all members in the workspace. + +ifndef::noall[] +*--all*:: + Deprecated alias for `--workspace`. +endif::noall[] + +*--exclude* _SPEC_...:: + Exclude the specified packages. Must be used in conjunction with the + `--workspace` flag. This flag may be specified multiple times. diff --git a/src/doc/man/includes/section-profiles.md b/src/doc/man/includes/section-profiles.md new file mode 100644 index 000000000..85f208997 --- /dev/null +++ b/src/doc/man/includes/section-profiles.md @@ -0,0 +1,26 @@ +== PROFILES + +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +linkcargo:reference/profiles.html[the reference] +for more details. + +Profile selection depends on the target and crate being built. By default the +`dev` or `test` profiles are used. If the `--release` flag is given, then the +`release` or `bench` profiles are used. + +[%autowidth] +|=== +|Target |Default Profile |`--release` Profile + +|lib, bin, example +|`dev` +|`release` + +|test, bench, or any target + + in "test" or "bench" mode +|`test` +|`bench` +|=== + +Dependencies use the `dev`/`release` profiles. diff --git a/src/doc/man/options-common.adoc b/src/doc/man/options-common.adoc deleted file mode 100644 index aa0e24f52..000000000 --- a/src/doc/man/options-common.adoc +++ /dev/null @@ -1,14 +0,0 @@ -*+TOOLCHAIN*:: - If Cargo has been installed with rustup, and the first argument to `cargo` - begins with `+`, it will be interpreted as a rustup toolchain name (such - as `+stable` or `+nightly`). - See the link:https://github.com/rust-lang/rustup/[rustup documentation] - for more information about how toolchain overrides work. - -*-h*:: -*--help*:: - Prints help information. - -*-Z* _FLAG_...:: - Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for - details. diff --git a/src/doc/man/options-display.adoc b/src/doc/man/options-display.adoc deleted file mode 100644 index cc2e22633..000000000 --- a/src/doc/man/options-display.adoc +++ /dev/null @@ -1,22 +0,0 @@ -*-v*:: -*--verbose*:: - Use verbose output. May be specified twice for "very verbose" output which - includes extra output such as dependency warnings and build script output. - May also be specified with the `term.verbose` - linkcargo:reference/config.html[config value]. - -*-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` -linkcargo:reference/config.html[config value]. diff --git a/src/doc/man/options-features.adoc b/src/doc/man/options-features.adoc deleted file mode 100644 index 2161ad967..000000000 --- a/src/doc/man/options-features.adoc +++ /dev/null @@ -1,23 +0,0 @@ -=== 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. diff --git a/src/doc/man/options-index.adoc b/src/doc/man/options-index.adoc deleted file mode 100644 index 1321866ba..000000000 --- a/src/doc/man/options-index.adoc +++ /dev/null @@ -1,2 +0,0 @@ -*--index* _INDEX_:: - The URL of the registry index to use. diff --git a/src/doc/man/options-jobs.adoc b/src/doc/man/options-jobs.adoc deleted file mode 100644 index 9d817426b..000000000 --- a/src/doc/man/options-jobs.adoc +++ /dev/null @@ -1,5 +0,0 @@ -*-j* _N_:: -*--jobs* _N_:: - Number of parallel jobs to run. May also be specified with the - `build.jobs` linkcargo:reference/config.html[config value]. Defaults to - the number of CPUs. diff --git a/src/doc/man/options-locked.adoc b/src/doc/man/options-locked.adoc deleted file mode 100644 index 45bbfa511..000000000 --- a/src/doc/man/options-locked.adoc +++ /dev/null @@ -1,24 +0,0 @@ -*--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 man:cargo-fetch[1] command to download dependencies before going -offline. -+ -May also be specified with the `net.offline` linkcargo:reference/config.html[config value]. diff --git a/src/doc/man/options-manifest-path.adoc b/src/doc/man/options-manifest-path.adoc deleted file mode 100644 index 79a2394a6..000000000 --- a/src/doc/man/options-manifest-path.adoc +++ /dev/null @@ -1,3 +0,0 @@ -*--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. diff --git a/src/doc/man/options-message-format.adoc b/src/doc/man/options-message-format.adoc deleted file mode 100644 index 818d78f81..000000000 --- a/src/doc/man/options-message-format.adoc +++ /dev/null @@ -1,18 +0,0 @@ -*--message-format* _FMT_:: - The output format for diagnostic messages. Can be specified multiple times - and consists of comma-separated values. Valid values: -+ -- `human` (default): Display in a human-readable text format. -- `short`: Emit shorter, human-readable text messages. -- `json`: Emit JSON messages to stdout. See - linkcargo:reference/external-tools.html#json-messages[the reference] - 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. diff --git a/src/doc/man/options-new.adoc b/src/doc/man/options-new.adoc deleted file mode 100644 index 2218599ae..000000000 --- a/src/doc/man/options-new.adoc +++ /dev/null @@ -1,29 +0,0 @@ -*--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 linkcargo:reference/config.html[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. diff --git a/src/doc/man/options-package.adoc b/src/doc/man/options-package.adoc deleted file mode 100644 index c0cfbc35e..000000000 --- a/src/doc/man/options-package.adoc +++ /dev/null @@ -1,7 +0,0 @@ -By default, the package in the current working directory is selected. The `-p` -flag can be used to choose a different package in a workspace. - -*-p* _SPEC_:: -*--package* _SPEC_:: - The package to convert:lowercase[{actionverb}]. See man:cargo-pkgid[1] for - the SPEC format. diff --git a/src/doc/man/options-packages.adoc b/src/doc/man/options-packages.adoc deleted file mode 100644 index dbddfb9c0..000000000 --- a/src/doc/man/options-packages.adoc +++ /dev/null @@ -1,27 +0,0 @@ -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_...:: - {actionverb} only the specified packages. See man:cargo-pkgid[1] for the - SPEC format. This flag may be specified multiple times. - -*--workspace*:: - {actionverb} all members in the workspace. - -ifndef::noall[] -*--all*:: - Deprecated alias for `--workspace`. -endif::noall[] - -*--exclude* _SPEC_...:: - Exclude the specified packages. Must be used in conjunction with the - `--workspace` flag. This flag may be specified multiple times. diff --git a/src/doc/man/options-profile.adoc b/src/doc/man/options-profile.adoc deleted file mode 100644 index 3c5ad14c7..000000000 --- a/src/doc/man/options-profile.adoc +++ /dev/null @@ -1,6 +0,0 @@ -*--profile* _NAME_:: - Changes convert:lowercase[{actionverb}] behavior. Currently only `test` is - supported, which will convert:lowercase[{actionverb}] with the - `#[cfg(test)]` attribute enabled. This is useful to have it - convert:lowercase[{actionverb}] unit tests which are usually excluded via - the `cfg` attribute. This does not change the actual profile used. diff --git a/src/doc/man/options-registry.adoc b/src/doc/man/options-registry.adoc deleted file mode 100644 index a0c4c27c8..000000000 --- a/src/doc/man/options-registry.adoc +++ /dev/null @@ -1,4 +0,0 @@ -*--registry* _REGISTRY_:: - Name of the registry to use. Registry names are defined in linkcargo:reference/config.html[Cargo config files]. - If not specified, the default registry is used, which is defined by the - `registry.default` config key which defaults to `crates-io`. diff --git a/src/doc/man/options-release.adoc b/src/doc/man/options-release.adoc deleted file mode 100644 index e99539172..000000000 --- a/src/doc/man/options-release.adoc +++ /dev/null @@ -1,3 +0,0 @@ -*--release*:: - {actionverb} optimized artifacts with the `release` profile. See the - <> section for details on how this affects profile selection. diff --git a/src/doc/man/options-target-dir.adoc b/src/doc/man/options-target-dir.adoc deleted file mode 100644 index f044bd712..000000000 --- a/src/doc/man/options-target-dir.adoc +++ /dev/null @@ -1,5 +0,0 @@ -*--target-dir* _DIRECTORY_:: - Directory for all generated artifacts and intermediate files. May also be - specified with the `CARGO_TARGET_DIR` environment variable, or the - `build.target-dir` linkcargo:reference/config.html[config value]. Defaults - to `target` in the root of the workspace. diff --git a/src/doc/man/options-target-triple.adoc b/src/doc/man/options-target-triple.adoc deleted file mode 100644 index 9cb6d7c85..000000000 --- a/src/doc/man/options-target-triple.adoc +++ /dev/null @@ -1,12 +0,0 @@ -*--target* _TRIPLE_:: - {actionverb} 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` -linkcargo:reference/config.html[config value]. -+ -Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -linkcargo:guide/build-cache.html[build cache] documentation for more details. diff --git a/src/doc/man/options-targets-lib-bin.adoc b/src/doc/man/options-targets-lib-bin.adoc deleted file mode 100644 index 8668ba84b..000000000 --- a/src/doc/man/options-targets-lib-bin.adoc +++ /dev/null @@ -1,8 +0,0 @@ -*--lib*:: - {actionverb} the package's library. - -*--bin* _NAME_...:: - {actionverb} the specified binary. This flag may be specified multiple times. - -*--bins*:: - {actionverb} all binary targets. diff --git a/src/doc/man/options-targets.adoc b/src/doc/man/options-targets.adoc deleted file mode 100644 index 6a8a46cd7..000000000 --- a/src/doc/man/options-targets.adoc +++ /dev/null @@ -1,39 +0,0 @@ -Passing target selection flags will convert:lowercase[{actionverb}] only the -specified targets. - -include::options-targets-lib-bin.adoc[] - -*--example* _NAME_...:: - {actionverb} the specified example. This flag may be specified multiple times. - -*--examples*:: - {actionverb} all example targets. - -*--test* _NAME_...:: - {actionverb} the specified integration test. This flag may be specified multiple - times. - -*--tests*:: - {actionverb} all targets in test mode that have the `test = true` manifest - flag set. By default this includes the library and binaries built as - unittests, and integration tests. Be aware that this will also build any - required dependencies, so the lib target may be built twice (once as a - unittest, and once as a dependency for binaries, integration tests, etc.). - Targets may be enabled or disabled by setting the `test` flag in the - manifest settings for the target. - -*--bench* _NAME_...:: - {actionverb} the specified benchmark. This flag may be specified multiple times. - -*--benches*:: - {actionverb} all targets in benchmark mode that have the `bench = true` - manifest flag set. By default this includes the library and binaries built - as benchmarks, and bench targets. Be aware that this will also build any - required dependencies, so the lib target may be built twice (once as a - benchmark, and once as a dependency for binaries, benchmarks, etc.). - Targets may be enabled or disabled by setting the `bench` flag in the - manifest settings for the target. - -*--all-targets*:: - {actionverb} all targets. This is equivalent to specifying `--lib --bins - --tests --benches --examples`. diff --git a/src/doc/man/options-test.adoc b/src/doc/man/options-test.adoc deleted file mode 100644 index 0cdcb3d7e..000000000 --- a/src/doc/man/options-test.adoc +++ /dev/null @@ -1,8 +0,0 @@ -*--no-run*:: - Compile, but don't run {nouns}. - -*--no-fail-fast*:: - Run all {nouns} regardless of failure. Without this flag, Cargo will exit - after the first executable fails. The Rust test harness will run all - {nouns} within the executable to completion, this flag only applies to - the executable as a whole. diff --git a/src/doc/man/options-token.adoc b/src/doc/man/options-token.adoc deleted file mode 100644 index 5f25ffbf2..000000000 --- a/src/doc/man/options-token.adoc +++ /dev/null @@ -1,10 +0,0 @@ -*--token* _TOKEN_:: - API token to use when authenticating. This overrides the token stored in - the credentials file (which is created by man:cargo-login[1]). -+ -linkcargo:reference/config.html[Cargo config] environment variables can be -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. diff --git a/src/doc/man/section-environment.adoc b/src/doc/man/section-environment.adoc deleted file mode 100644 index 5cc69e995..000000000 --- a/src/doc/man/section-environment.adoc +++ /dev/null @@ -1,4 +0,0 @@ -== ENVIRONMENT - -See linkcargo:reference/environment-variables.html[the reference] for -details on environment variables that Cargo reads. diff --git a/src/doc/man/section-exit-status.adoc b/src/doc/man/section-exit-status.adoc deleted file mode 100644 index 427b3903c..000000000 --- a/src/doc/man/section-exit-status.adoc +++ /dev/null @@ -1,7 +0,0 @@ -== Exit Status - -0:: - Cargo succeeded. - -101:: - Cargo failed to complete. diff --git a/src/doc/man/section-profiles.adoc b/src/doc/man/section-profiles.adoc deleted file mode 100644 index 85f208997..000000000 --- a/src/doc/man/section-profiles.adoc +++ /dev/null @@ -1,26 +0,0 @@ -== PROFILES - -Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -linkcargo:reference/profiles.html[the reference] -for more details. - -Profile selection depends on the target and crate being built. By default the -`dev` or `test` profiles are used. If the `--release` flag is given, then the -`release` or `bench` profiles are used. - -[%autowidth] -|=== -|Target |Default Profile |`--release` Profile - -|lib, bin, example -|`dev` -|`release` - -|test, bench, or any target + - in "test" or "bench" mode -|`test` -|`bench` -|=== - -Dependencies use the `dev`/`release` profiles.