diff options
Diffstat (limited to 'src/doc/man')
100 files changed, 12371 insertions, 0 deletions
diff --git a/src/doc/man/cargo-add.md b/src/doc/man/cargo-add.md new file mode 100644 index 0000000..c9bb237 --- /dev/null +++ b/src/doc/man/cargo-add.md @@ -0,0 +1,173 @@ +# cargo-add(1) + +{{*set actionverb="Add"}} +{{*set nouns="adds"}} + +## NAME + +cargo-add --- Add dependencies to a Cargo.toml manifest file + +## SYNOPSIS + +`cargo add` [_options_] _crate_...\ +`cargo add` [_options_] `--path` _path_\ +`cargo add` [_options_] `--git` _url_ [_crate_...]\ + + +## DESCRIPTION + +This command can add or modify dependencies. + +The source for the dependency can be specified with: + +* _crate_`@`_version_: Fetch from a registry with a version constraint of "_version_" +* `--path` _path_: Fetch from the specified _path_ +* `--git` _url_: Pull from a git repo at _url_ + +If no source is specified, then a best effort will be made to select one, including: + +* Existing dependencies in other tables (like `dev-dependencies`) +* Workspace members +* Latest release in the registry + +When you add a package that is already present, the existing entry will be updated with the flags specified. + +Upon successful invocation, the enabled (`+`) and disabled (`-`) [features] of the specified +dependency will be listed in the command's output. + +[features]: ../reference/features.md + +## OPTIONS + +### Source options + +{{#options}} + +{{#option "`--git` _url_" }} +[Git URL to add the specified crate from](../reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories). +{{/option}} + +{{#option "`--branch` _branch_" }} +Branch to use when adding from git. +{{/option}} + +{{#option "`--tag` _tag_" }} +Tag to use when adding from git. +{{/option}} + +{{#option "`--rev` _sha_" }} +Specific commit to use when adding from git. +{{/option}} + +{{#option "`--path` _path_" }} +[Filesystem path](../reference/specifying-dependencies.html#specifying-path-dependencies) to local crate to add. +{{/option}} + +{{> options-registry }} + +{{/options}} + +### Section options + +{{#options}} + +{{#option "`--dev`" }} +Add as a [development dependency](../reference/specifying-dependencies.html#development-dependencies). +{{/option}} + +{{#option "`--build`" }} +Add as a [build dependency](../reference/specifying-dependencies.html#build-dependencies). +{{/option}} + +{{#option "`--target` _target_" }} +Add as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies). +{{/option}} + +{{/options}} + + +</dl> + +### Dependency options + +{{#options}} + +{{#option "`--dry-run`" }} +Don't actually write the manifest +{{/option}} + +{{#option "`--rename` _name_" }} +[Rename](../reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml) the dependency. +{{/option}} + +{{#option "`--optional`" }} +Mark the dependency as [optional](../reference/features.html#optional-dependencies). +{{/option}} + +{{#option "`--no-optional`" }} +Mark the dependency as [required](../reference/features.html#optional-dependencies). +{{/option}} + +{{#option "`--no-default-features`" }} +Disable the [default features](../reference/features.html#dependency-features). +{{/option}} + +{{#option "`--default-features`" }} +Re-enable the [default features](../reference/features.html#dependency-features). +{{/option}} + +{{#option "`-F` _features_" "`--features` _features_" }} +Space or comma separated list of [features to +activate](../reference/features.html#dependency-features). When adding multiple +crates, the features for a specific crate may be enabled with +`package-name/feature-name` syntax. This flag may be specified multiple times, +which enables all specified features. +{{/option}} + +{{/options}} + + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{#option "`-p` _spec_" "`--package` _spec_" }} +Add dependencies to only the specified package. +{{/option}} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Add `regex` as a dependency + + cargo add regex + +2. Add `trybuild` as a dev-dependency + + cargo add --dev trybuild + +3. Add an older version of `nom` as a dependency + + cargo add nom@5 + +4. Add support for serializing data structures to json with `derive`s + + cargo add serde serde_json -F serde/derive + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-remove" 1}} diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md new file mode 100644 index 0000000..32c98da --- /dev/null +++ b/src/doc/man/cargo-bench.md @@ -0,0 +1,164 @@ +# cargo-bench(1) +{{*set actionverb="Benchmark"}} +{{*set nouns="benchmarks"}} +{{*set multitarget=true}} + +## NAME + +cargo-bench --- Execute benchmarks of a package + +## SYNOPSIS + +`cargo bench` [_options_] [_benchname_] [`--` _bench-options_] + +## DESCRIPTION + +Compile and execute benchmarks. + +The benchmark filtering argument _benchname_ and all the arguments following +the two dashes (`--`) are passed to the benchmark binaries and thus to +_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after `--` go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of `cargo bench -- --help` and check out the rustc +book's chapter on how tests work at +<https://doc.rust-lang.org/rustc/tests/index.html>. + +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 a +special executable by linking your code with libtest. The executable +automatically runs all functions annotated with the `#[bench]` attribute. +Cargo passes the `--bench` flag to the test harness to tell it to run +only benchmarks. + +The libtest harness may be disabled by setting `harness = false` in the target +manifest settings, in which case your code will need to provide its own `main` +function to handle running benchmarks. + +> **Note**: The +> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html) +> is currently unstable and only available on the +> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html). +> There are some packages available on +> [crates.io](https://crates.io/keywords/benchmark) that may help with +> running benchmarks on the stable channel, such as +> [Criterion](https://crates.io/crates/criterion). + +By default, `cargo bench` uses the [`bench` profile], which enables +optimizations and disables debugging information. If you need to debug a +benchmark, you can use the `--profile=dev` command-line option to switch to +the dev profile. You can then run the debug-enabled benchmark within a +debugger. + +[`bench` profile]: ../reference/profiles.html#bench + +## OPTIONS + +### Benchmark Options + +{{> options-test }} + +{{> section-package-selection }} + +### 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. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +By default the Rust test harness hides output from benchmark execution to keep +results readable. Benchmark output can be recovered (e.g., for debugging) by +passing `--nocapture` to the benchmark binaries: + + cargo bench -- --nocapture + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +The `--jobs` argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread. + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build and execute all the benchmarks of the current package: + + cargo bench + +2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-test" 1}} diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md new file mode 100644 index 0000000..9861444 --- /dev/null +++ b/src/doc/man/cargo-build.md @@ -0,0 +1,116 @@ +# cargo-build(1) +{{*set actionverb="Build"}} +{{*set multitarget=true}} + +## NAME + +cargo-build --- Compile the current package + +## SYNOPSIS + +`cargo build` [_options_] + +## DESCRIPTION + +Compile local packages and all of their dependencies. + +## OPTIONS + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo build` will build all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} + +{{#option "`--out-dir` _directory_" }} +Copy final artifacts to this directory. + +This option is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z unstable-options` flag to enable. +See <https://github.com/rust-lang/cargo/issues/6790> for more information. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} + +{{#option "`--build-plan`" }} +Outputs a series of JSON messages to stdout that indicate the commands to run +the build. + +This option is unstable and available only on the +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) +and requires the `-Z unstable-options` flag to enable. +See <https://github.com/rust-lang/cargo/issues/5579> for more information. +{{/option}} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build the local package and all of its dependencies: + + cargo build + +2. Build with optimizations: + + cargo build --release + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-rustc" 1}} diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md new file mode 100644 index 0000000..055adff --- /dev/null +++ b/src/doc/man/cargo-check.md @@ -0,0 +1,99 @@ +# cargo-check(1) +{{*set actionverb="Check"}} +{{*set multitarget=true}} + +## 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. Some diagnostics and errors are only emitted during code +generation, so they inherently won't be reported with `cargo check`. + +## OPTIONS + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo check` will check all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile-legacy-check }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Check the local package for errors: + + cargo check + +2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +## SEE ALSO +{{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 0000000..3222f7b --- /dev/null +++ b/src/doc/man/cargo-clean.md @@ -0,0 +1,88 @@ +# cargo-clean(1) +{{*set actionverb="Clean"}} +{{*set multitarget=true}} + +## 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. + +{{#options}} +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Clean only the specified packages. This flag may be specified +multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format. +{{/option}} +{{/options}} + +### Clean Options + +{{#options}} + +{{#option "`--doc`" }} +This option will cause `cargo clean` to remove only the `doc` directory in +the target directory. +{{/option}} + +{{#option "`--release`" }} +Remove all artifacts in the `release` directory. +{{/option}} + +{{#option "`--profile` _name_" }} +Remove all artifacts in the directory with the given profile name. +{{/option}} + +{{> options-target-dir }} + +{{> options-target-triple }} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Remove the entire target directory: + + cargo clean + +2. 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.md b/src/doc/man/cargo-doc.md new file mode 100644 index 0000000..9d5b776 --- /dev/null +++ b/src/doc/man/cargo-doc.md @@ -0,0 +1,129 @@ +# cargo-doc(1) +{{*set actionverb="Document"}} +{{*set multitarget=true}} + +## 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 + +{{#options}} + +{{#option "`--open`" }} +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the `BROWSER` environment variable +or use the [`doc.browser`](../reference/config.html#docbrowser) configuration +option. +{{/option}} + +{{#option "`--no-deps`" }} +Do not build documentation for dependencies. +{{/option}} + +{{#option "`--document-private-items`" }} +Include non-public items in the documentation. This will be enabled by default if documenting a binary target. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo doc` will document all +binary and library targets of the selected package. The binary will be skipped +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. + +{{#options}} +{{> options-targets-lib-bin }} + +{{#option "`--example` _name_..." }} +{{actionverb}} the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +{{/option}} + +{{#option "`--examples`" }} +{{actionverb}} all example targets. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-fetch.md new file mode 100644 index 0000000..c31166a --- /dev/null +++ b/src/doc/man/cargo-fetch.md @@ -0,0 +1,65 @@ +# cargo-fetch(1) +{{*set actionverb="Fetch"}} +{{*set target-default-to-all-arch=true}} +{{*set multitarget=true}} + +## 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 will be able to run offline after a `cargo +fetch` unless the lock file changes. + +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. + +If `--target` is not specified, then all target dependencies are fetched. + +See also the [cargo-prefetch](https://crates.io/crates/cargo-prefetch) +plugin which adds a command to download popular crates. This may be useful if +you plan to use Cargo without a network with the `--offline` flag. + +## OPTIONS + +### Fetch options + +{{#options}} +{{> options-target-triple }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-fix.md new file mode 100644 index 0000000..64fe299 --- /dev/null +++ b/src/doc/man/cargo-fix.md @@ -0,0 +1,182 @@ +# cargo-fix(1) +{{*set actionverb="Fix"}} +{{*set multitarget=true}} + +## 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! + +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 apply all fixes to the current package, you can run: + + cargo fix + +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 --features foo + +Similarly, other `cfg` expressions like platform-specific code will need to +pass `--target` to fix code for the given target. + + cargo fix --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>. + +### Edition migration + +The `cargo fix` subcommand can also be used to migrate a package from one +[edition] to the next. The general procedure is: + +1. Run `cargo fix --edition`. Consider also using the `--all-features` flag if + your project has multiple features. You may also want to run `cargo fix + --edition` multiple times with different `--target` flags if your project + has platform-specific code gated by `cfg` attributes. +2. Modify `Cargo.toml` to set the [edition field] to the new edition. +3. Run your project tests to verify that everything still works. If new + warnings are issued, you may want to consider running `cargo fix` again + (without the `--edition` flag) to apply any suggestions given by the + compiler. + +And hopefully that's it! Just keep in mind of the caveats mentioned above that +`cargo fix` cannot update code for inactive features or `cfg` expressions. +Also, in some rare cases the compiler is unable to automatically migrate all +code to the new edition, and this may require manual changes after building +with the new edition. + +[edition]: https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html +[edition field]: ../reference/manifest.html#the-edition-field + +## OPTIONS + +### Fix options + +{{#options}} + +{{#option "`--broken-code`" }} +Fix code even if it already has compiler errors. This is useful if `cargo fix` +fails to apply the changes. It will apply the changes and leave the broken +code in the working directory for you to inspect and manually fix. +{{/option}} + +{{#option "`--edition`" }} +Apply changes that will update the code to the next edition. This will not +update the edition in the `Cargo.toml` manifest, which must be updated +manually after `cargo fix --edition` has finished. +{{/option}} + +{{#option "`--edition-idioms`" }} +Apply suggestions that will update code to the preferred style for the current +edition. +{{/option}} + +{{#option "`--allow-no-vcs`" }} +Fix code even if a VCS was not detected. +{{/option}} + +{{#option "`--allow-dirty`" }} +Fix code even if the working directory has changes. +{{/option}} + +{{#option "`--allow-staged`" }} +Fix code even if the working directory has staged changes. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Target Selection + +When no target selection options are given, `cargo fix` will fix all targets +(`--all-targets` implied). Binaries are skipped if they have +`required-features` that are missing. + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile-legacy-check }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Apply compiler suggestions to the local package: + + cargo fix + +2. Update a package to prepare it for the next edition: + + cargo fix --edition + +3. 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.md b/src/doc/man/cargo-generate-lockfile.md new file mode 100644 index 0000000..3a2f52b --- /dev/null +++ b/src/doc/man/cargo-generate-lockfile.md @@ -0,0 +1,49 @@ +# cargo-generate-lockfile(1) + +## NAME + +cargo-generate-lockfile --- Generate the lockfile for a package + +## SYNOPSIS + +`cargo generate-lockfile` [_options_] + +## DESCRIPTION + +This command will create the `Cargo.lock` lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt with the latest +available version of every package. + +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 + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-help.md new file mode 100644 index 0000000..4a5a8f5 --- /dev/null +++ b/src/doc/man/cargo-help.md @@ -0,0 +1,26 @@ +# cargo-help(1) + +## NAME + +cargo-help --- Get help for a Cargo command + +## SYNOPSIS + +`cargo help` [_subcommand_] + +## DESCRIPTION + +Prints a help message for the given command. + +## EXAMPLES + +1. Get help for a command: + + cargo help build + +2. Help is also available with the `--help` flag: + + cargo build --help + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-init.md b/src/doc/man/cargo-init.md new file mode 100644 index 0000000..cd8e623 --- /dev/null +++ b/src/doc/man/cargo-init.md @@ -0,0 +1,51 @@ +# cargo-init(1) + +## NAME + +cargo-init --- Create a new Cargo package in an existing directory + +## SYNOPSIS + +`cargo init` [_options_] [_path_] + +## DESCRIPTION + +This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory. + +If there are typically-named Rust source files already in the directory, those +will be used. If not, then a sample `src/main.rs` file will be created, or +`src/lib.rs` if `--lib` is passed. + +If the directory is not already in a VCS repository, then a new repository +is created (see `--vcs` below). + +See {{man "cargo-new" 1}} for a similar command which will create a new package in +a new directory. + +## OPTIONS + +### Init Options + +{{> options-new }} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-install.md new file mode 100644 index 0000000..14c2296 --- /dev/null +++ b/src/doc/man/cargo-install.md @@ -0,0 +1,229 @@ +# cargo-install(1) +{{*set actionverb="Install"}} +{{*set temp-target-dir=true}} + +## NAME + +cargo-install --- Build and install a Rust binary + +## SYNOPSIS + +`cargo install` [_options_] _crate_[@_version_]...\ +`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. + +{{> description-install-root }} + +There are multiple sources from which a crate can be installed. The default +location is crates.io but the `--git`, `--path`, and `--registry` flags can +change this source. If the source contains more than one package (such as +crates.io or a git repository with multiple crates) the _crate_ argument is +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 profile (`--profile`). +- 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. + +### Dealing with the Lockfile + +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. + +### Configuration Discovery + +This command operates on system or user level, not project level. +This means that the local [configuration discovery] is ignored. +Instead, the configuration discovery begins at `$CARGO_HOME/config.toml`. +If the package is installed with `--path $PATH`, the local configuration +will be used, beginning discovery at `$PATH/.cargo/config.toml`. + +[configuration discovery]: ../reference/config.html#hierarchical-structure + +## OPTIONS + +### Install Options + +{{#options}} + +{{#option "`--vers` _version_" "`--version` _version_" }} +Specify a version to install. This may be a [version +requirement](../reference/specifying-dependencies.md), like `~1.2`, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as `^` or `~`), then it must be in the form +_MAJOR.MINOR.PATCH_, and will install exactly that version; it is *not* +treated as a caret requirement like Cargo dependencies are. +{{/option}} + +{{#option "`--git` _url_" }} +Git URL to install the specified crate from. +{{/option}} + +{{#option "`--branch` _branch_" }} +Branch to use when installing from git. +{{/option}} + +{{#option "`--tag` _tag_" }} +Tag to use when installing from git. +{{/option}} + +{{#option "`--rev` _sha_" }} +Specific commit to use when installing from git. +{{/option}} + +{{#option "`--path` _path_" }} +Filesystem path to local crate to install. +{{/option}} + +{{#option "`--list`" }} +List all installed packages and their versions. +{{/option}} + +{{#option "`-f`" "`--force`" }} +Force overwriting existing crates or binaries. This can be used if a package +has installed a binary with the same name as another package. This is also +useful if something has changed on the system that you want to rebuild with, +such as a newer version of `rustc`. +{{/option}} + +{{#option "`--no-track`" }} +By default, Cargo keeps track of the installed packages with a metadata file +stored in the installation root directory. This flag tells Cargo not to use or +create that file. With this flag, Cargo will refuse to overwrite any existing +files unless the `--force` flag is used. This also disables Cargo's ability to +protect against multiple concurrent invocations of Cargo installing at the +same time. +{{/option}} + +{{#option "`--bin` _name_..." }} +Install only the specified binary. +{{/option}} + +{{#option "`--bins`" }} +Install all binaries. +{{/option}} + +{{#option "`--example` _name_..." }} +Install only the specified example. +{{/option}} + +{{#option "`--examples`" }} +Install all examples. +{{/option}} + +{{#option "`--root` _dir_" }} +Directory to install packages into. +{{/option}} + +{{> options-registry }} + +{{> options-index }} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-target-dir }} + +{{#option "`--debug`" }} +Build with the `dev` profile instead the `release` profile. +See also the `--profile` option for choosing a specific profile by name. +{{/option}} + +{{> options-profile }} + +{{> options-timings }} + +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-locked }} +{{/options}} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Install or upgrade a package from crates.io: + + cargo install ripgrep + +2. Install or reinstall the package in the current directory: + + cargo install --path . + +3. View the list of installed packages: + + cargo install --list + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-uninstall" 1}}, {{man "cargo-search" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-locate-project.md b/src/doc/man/cargo-locate-project.md new file mode 100644 index 0000000..4ebf36d --- /dev/null +++ b/src/doc/man/cargo-locate-project.md @@ -0,0 +1,66 @@ +# cargo-locate-project(1) + +## NAME + +cargo-locate-project --- Print a JSON representation of a Cargo.toml file's location + +## SYNOPSIS + +`cargo locate-project` [_options_] + +## DESCRIPTION + +This command will print a JSON object to stdout with the full path to the manifest. The +manifest is found by searching upward for a file named `Cargo.toml` starting from the current +working directory. + +If the project happens to be a part of a workspace, the manifest of the project, rather than +the workspace root, is output. This can be overridden by the `--workspace` flag. The root +workspace is found by traversing further upward or by using the field `package.workspace` after +locating the manifest of a workspace member. + +## OPTIONS + +{{#options}} + +{{#option "`--workspace`" }} +Locate the `Cargo.toml` at the root of the workspace, as opposed to the current +workspace member. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} + +{{#option "`--message-format` _fmt_" }} +The representation in which to print the project location. Valid values: + +- `json` (default): JSON object with the path under the key "root". +- `plain`: Just the path. +{{/option}} + +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-login.md new file mode 100644 index 0000000..11c663c --- /dev/null +++ b/src/doc/man/cargo-login.md @@ -0,0 +1,51 @@ +# cargo-login(1) + +## NAME + +cargo-login --- Save an API token from the registry locally + +## SYNOPSIS + +`cargo login` [_options_] [_token_] + +## DESCRIPTION + +This command will save the API token to disk so that commands that require +authentication, such as {{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 + +{{#options}} +{{> options-registry }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-metadata.md new file mode 100644 index 0000000..4f9032d --- /dev/null +++ b/src/doc/man/cargo-metadata.md @@ -0,0 +1,353 @@ +# cargo-metadata(1) + +## NAME + +cargo-metadata --- Machine-readable metadata about the current package + +## SYNOPSIS + +`cargo metadata` [_options_] + +## DESCRIPTION + +Output JSON to stdout containing information about the workspace members and +resolved dependencies of the current package. + +It is recommended to include the `--format-version` flag to future-proof +your code to ensure the output is in the format you are expecting. + +See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata) +for a Rust API for reading the metadata. + +## OUTPUT FORMAT + +The output has the following format: + +```javascript +{ + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* The file system path for a local path dependency. + not present if not a path dependency. + */ + "path": "/path/to/dep", + /* 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 the target should be documented by `cargo doc`. */ + "doc": true, + /* 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 <user@example.com>" + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", + /* 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 homepage value from the manifest or null if not specified. */ + "homepage": "https://rust-lang.org", + /* The documentation value from the manifest or null if not specified. */ + "documentation": "https://doc.rust-lang.org/stable/std", + /* 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 + +{{#options}} + +{{#option "`--no-deps`" }} +Output information only about the workspace members and don't fetch +dependencies. +{{/option}} + +{{#option "`--format-version` _version_" }} +Specify the version of the output format to use. Currently `1` is the only +possible value. +{{/option}} + +{{#option "`--filter-platform` _triple_" }} +This filters the `resolve` output to only include dependencies for the +given [target triple](../appendix/glossary.html#target). +Without this flag, the resolve includes all targets. + +Note that the dependencies listed in the "packages" array still includes all +dependencies. Each package definition is intended to be an unaltered +reproduction of the information within `Cargo.toml`. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Output JSON about the current package: + + cargo metadata --format-version=1 + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-new.md b/src/doc/man/cargo-new.md new file mode 100644 index 0000000..ea6182a --- /dev/null +++ b/src/doc/man/cargo-new.md @@ -0,0 +1,46 @@ +# cargo-new(1) + +## NAME + +cargo-new --- Create a new Cargo package + +## SYNOPSIS + +`cargo new` [_options_] _path_ + +## DESCRIPTION + +This command will create a new Cargo package in the given directory. This +includes a simple template with a `Cargo.toml` manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see `--vcs` below). + +See {{man "cargo-init" 1}} for a similar command which will create a new manifest +in an existing directory. + +## OPTIONS + +### New Options + +{{> options-new }} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-owner.md new file mode 100644 index 0000000..3279169 --- /dev/null +++ b/src/doc/man/cargo-owner.md @@ -0,0 +1,81 @@ +# cargo-owner(1) + +## NAME + +cargo-owner --- Manage the owners of a crate on the registry + +## SYNOPSIS + +`cargo owner` [_options_] `--add` _login_ [_crate_]\ +`cargo owner` [_options_] `--remove` _login_ [_crate_]\ +`cargo owner` [_options_] `--list` [_crate_] + +## DESCRIPTION + +This command will modify the owners for a crate on the registry. Owners of a +crate can upload new versions and yank old versions. Non-team owners can also +modify the set of owners, so take care! + +This command requires you to be authenticated with either the `--token` option +or using {{man "cargo-login" 1}}. + +If the crate name is not specified, it will use the package name from the +current directory. + +See [the reference](../reference/publishing.html#cargo-owner) for more +information about owners and publishing. + +## OPTIONS + +### Owner Options + +{{#options}} + +{{#option "`-a`" "`--add` _login_..." }} +Invite the given user or team as an owner. +{{/option}} + +{{#option "`-r`" "`--remove` _login_..." }} +Remove the given user or team as an owner. +{{/option}} + +{{#option "`-l`" "`--list`" }} +List owners of a crate. +{{/option}} + +{{> options-token }} + +{{> options-index }} + +{{> options-registry }} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. List owners of a package: + + cargo owner --list foo + +2. Invite an owner to a package: + + cargo owner --add username foo + +3. Remove an owner from a package: + + cargo owner --remove username foo + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-login" 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 0000000..2000353 --- /dev/null +++ b/src/doc/man/cargo-package.md @@ -0,0 +1,138 @@ +# cargo-package(1) +{{*set actionverb="Package"}} +{{*set noall=true}} +{{*set multitarget=true}} + +## NAME + +cargo-package --- Assemble the local package into a distributable tarball + +## SYNOPSIS + +`cargo package` [_options_] + +## DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory. The resulting file will +be stored in the `target/package` directory. This performs the following +steps: + +1. Load and check the current workspace, performing some basic checks. + - Path dependencies are not allowed unless they have a version key. Cargo + will ignore the path key for dependencies in published packages. + `dev-dependencies` do not have this restriction. +2. Create the compressed `.crate` file. + - The original `Cargo.toml` file is rewritten and normalized. + - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the + manifest. + - `Cargo.lock` is automatically included if the package contains an + executable binary or example target. {{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`). +3. Extract the `.crate` file and build it to verify it can build. + - This will rebuild your package from scratch to ensure that it can be + built from a pristine state. The `--no-verify` flag can be used to skip + this step. +4. Check that build scripts did not modify any source files. + +The list of files included can be controlled with the `include` and `exclude` +fields in the manifest. + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +### .cargo_vcs_info.json format + +Will generate a `.cargo_vcs_info.json` in the following format + +```javascript +{ + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" +} +``` + +`path_in_vcs` will be set to a repo-relative path for packages +in subdirectories of the version control repository. + +## OPTIONS + +### Package Options + +{{#options}} + +{{#option "`-l`" "`--list`" }} +Print files included in a package without making one. +{{/option}} + +{{#option "`--no-verify`" }} +Don't verify the contents by building them. +{{/option}} + +{{#option "`--no-metadata`" }} +Ignore warnings about a lack of human-usable metadata (such as the description +or the license). +{{/option}} + +{{#option "`--allow-dirty`" }} +Allow working directories with uncommitted VCS changes to be packaged. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-target-dir }} + +{{/options}} + +{{> section-features }} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Create a compressed `.crate` file of the current package: + + cargo package + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md new file mode 100644 index 0000000..47ed133 --- /dev/null +++ b/src/doc/man/cargo-pkgid.md @@ -0,0 +1,89 @@ +# cargo-pkgid(1) + +## NAME + +cargo-pkgid --- Print a fully qualified package specification + +## SYNOPSIS + +`cargo pkgid` [_options_] [_spec_] + +## DESCRIPTION + +Given a _spec_ argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if _spec_ is ambiguous as to which package it refers to in +the dependency graph. If no _spec_ is given, then the specifier for the local +package is printed. + +This command requires that a lockfile is available and dependencies have been +fetched. + +A package specifier consists of a name, version, and source URL. You are +allowed to use partial specifiers to succinctly match a specific package as +long as it matches only one package. The format of a _spec_ can be one of the +following: + +SPEC Structure | Example SPEC +---------------------------|-------------- +_name_ | `bitflags` +_name_`@`_version_ | `bitflags@1.0.4` +_url_ | `https://github.com/rust-lang/cargo` +_url_`#`_version_ | `https://github.com/rust-lang/cargo#0.33.0` +_url_`#`_name_ | `https://github.com/rust-lang/crates.io-index#bitflags` +_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io@0.21.0` + +## OPTIONS + +### Package Selection + +{{#options}} + +{{#option "`-p` _spec_" "`--package` _spec_" }} +Get the package ID for the given package instead of the current package. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Retrieve package specification for `foo` package: + + cargo pkgid foo + +2. Retrieve package specification for version 1.0.0 of `foo`: + + cargo pkgid foo@1.0.0 + +3. Retrieve package specification for `foo` from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +4. Retrieve package specification for `foo` from a local package: + + cargo pkgid file:///path/to/local/package#foo + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-publish.md b/src/doc/man/cargo-publish.md new file mode 100644 index 0000000..4ccb5b5 --- /dev/null +++ b/src/doc/man/cargo-publish.md @@ -0,0 +1,117 @@ +# cargo-publish(1) +{{*set actionverb="Publish"}} +{{*set multitarget=true}} + +## 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: + +1. Performs a few checks, including: + - Checks the `package.publish` key in the manifest for restrictions on + which registries you are allowed to publish to. +2. Create a `.crate` file by following the steps in {{man "cargo-package" 1}}. +3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + +This command requires you to be authenticated with either the `--token` option +or using {{man "cargo-login" 1}}. + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +## OPTIONS + +### Publish Options + +{{#options}} + +{{#option "`--dry-run`" }} +Perform all checks without uploading. +{{/option}} + +{{> options-token }} + +{{#option "`--no-verify`" }} +Don't verify the contents by building them. +{{/option}} + +{{#option "`--allow-dirty`" }} +Allow working directories with uncommitted VCS changes to be packaged. +{{/option}} + +{{> options-index }} + +{{#option "`--registry` _registry_"}} +Name of the registry to publish to. Registry names are defined in [Cargo +config files](../reference/config.html). If not specified, and there is a +[`package.publish`](../reference/manifest.html#the-publish-field) field in +`Cargo.toml` with a single registry, then it will publish to that registry. +Otherwise it will use the default registry, which is defined by the +[`registry.default`](../reference/config.html#registrydefault) config key +which defaults to `crates-io`. +{{/option}} + +{{/options}} + +{{> section-options-package }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-target-dir }} + +{{/options}} + +{{> section-features }} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Publish the current package: + + cargo publish + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-package" 1}}, {{man "cargo-login" 1}} diff --git a/src/doc/man/cargo-remove.md b/src/doc/man/cargo-remove.md new file mode 100644 index 0000000..0722e6e --- /dev/null +++ b/src/doc/man/cargo-remove.md @@ -0,0 +1,92 @@ +# cargo-remove(1) +{{*set actionverb="Remove"}} +{{*set nouns="removes"}} + +## NAME + +cargo-remove --- Remove dependencies from a Cargo.toml manifest file + +## SYNOPSIS + +`cargo remove` [_options_] _dependency_... + +## DESCRIPTION + +Remove one or more dependencies from a `Cargo.toml` manifest. + +## OPTIONS + +### Section options + +{{#options}} + +{{#option "`--dev`" }} +Remove as a [development dependency](../reference/specifying-dependencies.html#development-dependencies). +{{/option}} + +{{#option "`--build`" }} +Remove as a [build dependency](../reference/specifying-dependencies.html#build-dependencies). +{{/option}} + +{{#option "`--target` _target_" }} +Remove as a dependency to the [given target platform](../reference/specifying-dependencies.html#platform-specific-dependencies). +{{/option}} + +{{/options}} + +### Miscellaneous Options + +{{#options}} + +{{#option "`--dry-run`" }} +Don't actually write to the manifest. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +### Package Selection + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Package to remove from. +{{/option}} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Remove `regex` as a dependency + + cargo remove regex + +2. Remove `trybuild` as a dev-dependency + + cargo remove --dev trybuild + +3. Remove `nom` from the `x86_64-pc-windows-gnu` dependencies table + + cargo remove --target x86_64-pc-windows-gnu nom + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-add" 1}} diff --git a/src/doc/man/cargo-report.md b/src/doc/man/cargo-report.md new file mode 100644 index 0000000..ba33617 --- /dev/null +++ b/src/doc/man/cargo-report.md @@ -0,0 +1,42 @@ +# cargo-report(1) + +## NAME + +cargo-report --- Generate and display various kinds of reports + +## SYNOPSIS + +`cargo report` _type_ [_options_] + +### DESCRIPTION + +Displays a report of the given _type_ --- currently, only `future-incompat` is supported + +## OPTIONS + +{{#options}} + +{{#option "`--id` _id_" }} +Show the report with the specified Cargo-generated id +{{/option}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Only display a report for the specified package +{{/option}} + +{{/options}} + +## EXAMPLES + +1. Display the latest future-incompat report: + + cargo report future-incompat + +2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +## SEE ALSO +[Future incompat report](../reference/future-incompat-report.html) + +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-run.md b/src/doc/man/cargo-run.md new file mode 100644 index 0000000..4b6b935 --- /dev/null +++ b/src/doc/man/cargo-run.md @@ -0,0 +1,111 @@ +# cargo-run(1) +{{*set 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 + +{{> section-options-package }} + +### 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. + +{{#options}} + +{{#option "`--bin` _name_" }} +Run the specified binary. +{{/option}} + +{{#option "`--example` _name_" }} +Run the specified example. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Build the local package and run its main target (assuming only one binary): + + cargo run + +2. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md new file mode 100644 index 0000000..f3b3723 --- /dev/null +++ b/src/doc/man/cargo-rustc.md @@ -0,0 +1,145 @@ +# cargo-rustc(1) +{{*set actionverb="Build"}} +{{*set multitarget=true}} + +## 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. + +{{> description-one-target }} +To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` +[environment variable](../reference/environment-variables.html) or the +`build.rustflags` [config value](../reference/config.html). + +## OPTIONS + +{{> section-options-package }} + +### Target Selection + +When no target selection options are given, `cargo rustc` will build all +binary and library targets of the selected package. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{#option "`--profile` _name_" }} +Build with the given profile. + +The `rustc` subcommand will treat the following named profiles with special behaviors: + +* `check` --- Builds in the same way as the {{man "cargo-check" 1}} command with + the `dev` profile. +* `test` --- Builds in the same way as the {{man "cargo-test" 1}} command, + enabling building in test mode which will enable tests and enable the `test` + cfg option. See [rustc + tests](https://doc.rust-lang.org/rustc/tests/index.html) for more detail. +* `bench` --- Builds in the same was as the {{man "cargo-bench" 1}} command, + similar to the `test` profile. + +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{#option "`--crate-type` _crate-type_"}} +Build for the given crate type. This flag accepts a comma-separated list of +1 or more crate types, of which the allowed values are the same as `crate-type` +field in the manifest for configurating a Cargo target. See +[`crate-type` field](../reference/cargo-targets.html#the-crate-type-field) +for possible values. + +If the manifest contains a list, and `--crate-type` is provided, +the command-line argument value will override what is in the manifest. + +This flag only works when building a `lib` or `example` library target. +{{/option}} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + +2. Try an experimental flag on the nightly compiler, such as this which prints + the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + +3. Override `crate-type` field in Cargo.toml with command-line option: + + cargo rustc --lib --crate-type lib,cdylib + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}}, {{man "rustc" 1}} diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md new file mode 100644 index 0000000..23be579 --- /dev/null +++ b/src/doc/man/cargo-rustdoc.md @@ -0,0 +1,116 @@ +# cargo-rustdoc(1) +{{*set actionverb="Document"}} +{{*set multitarget=true}} + +## 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. + +{{> description-one-target }} +To pass flags to all rustdoc processes spawned by Cargo, use the +`RUSTDOCFLAGS` [environment variable](../reference/environment-variables.html) +or the `build.rustdocflags` [config value](../reference/config.html). + +## OPTIONS + +### Documentation Options + +{{#options}} + +{{#option "`--open`" }} +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the `BROWSER` environment variable +or use the [`doc.browser`](../reference/config.html#docbrowser) configuration +option. +{{/option}} + +{{/options}} + +{{> section-options-package }} + +### Target Selection + +When no target selection options are given, `cargo rustdoc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} + +{{> options-message-format }} +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-manifest-path }} + +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +{{#options}} +{{> options-jobs }} +{{> options-keep-going }} +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-search.md new file mode 100644 index 0000000..f3d87cb --- /dev/null +++ b/src/doc/man/cargo-search.md @@ -0,0 +1,52 @@ +# cargo-search(1) + +## NAME + +cargo-search --- Search packages in crates.io + +## SYNOPSIS + +`cargo search` [_options_] [_query_...] + +## DESCRIPTION + +This performs a textual search for crates on <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 + +{{#options}} + +{{#option "`--limit` _limit_" }} +Limit the number of results (default: 10, max: 100). +{{/option}} + +{{> options-index }} + +{{> options-registry }} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-test.md new file mode 100644 index 0000000..0b6da16 --- /dev/null +++ b/src/doc/man/cargo-test.md @@ -0,0 +1,191 @@ +# cargo-test(1) +{{*set actionverb="Test"}} +{{*set nouns="tests"}} +{{*set multitarget=true}} + +## NAME + +cargo-test --- Execute unit and integration tests of a package + +## SYNOPSIS + +`cargo test` [_options_] [_testname_] [`--` _test-options_] + +## DESCRIPTION + +Compile and execute unit, integration, and documentation 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` and check out the rustc book's chapter on +how tests work at <https://doc.rust-lang.org/rustc/tests/index.html>. + +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 a special +executable by linking your code with libtest. The executable 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. + +If the package contains multiple test targets, each target compiles to a +special executable as aforementioned, and then is run serially. + +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 + +Documentation tests are also run by default, which is handled by `rustdoc`. It +extracts code samples from documentation comments of the library target, and +then executes them. + +Different from normal test targets, each code block compiles to a doctest +executable on the fly with `rustc`. These executables run in parallel in +separate processes. The compilation of a code block is in fact a part of test +function controlled by libtest, so some options such as `--jobs` might not +take effect. Note that this execution model of doctests is not guaranteed +and may change in the future; beware of depending on it. + +See the [rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information +on writing doc tests. + +## OPTIONS + +### Test Options + +{{> options-test }} + +{{> section-package-selection }} + +### 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. + +{{> options-targets-bin-auto-built }} + +{{> options-targets }} + +{{#options}} + +{{#option "`--doc`" }} +Test only the library's documentation. This cannot be mixed with other +target options. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} + +{{> options-profile }} + +{{> options-ignore-rust-version }} + +{{> options-timings }} + +{{/options}} + +### Output Options + +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options + +By default the Rust test harness hides output from test execution to keep +results readable. Test output can be recovered (e.g., for debugging) by passing +`--nocapture` to the test binaries: + + cargo test -- --nocapture + +{{#options}} + +{{> options-display }} + +{{> options-message-format }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options + +The `--jobs` argument affects the building of the test executable but does not +affect how many threads are used when running the tests. The Rust test harness +includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + +{{#options}} + +{{> options-jobs }} +{{> options-keep-going }} +{{> options-future-incompat }} + +{{/options}} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Execute all the unit and integration tests of the current package: + + cargo test + +2. Run only tests whose names match against a filter string: + + cargo test name_filter + +3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-bench" 1}}, [types of tests](../reference/cargo-targets.html#tests), [how to write tests](https://doc.rust-lang.org/rustc/tests/index.html) diff --git a/src/doc/man/cargo-tree.md b/src/doc/man/cargo-tree.md new file mode 100644 index 0000000..3e1da20 --- /dev/null +++ b/src/doc/man/cargo-tree.md @@ -0,0 +1,268 @@ +# cargo-tree(1) +{{*set actionverb="Display"}} +{{*set 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 elsewhere 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. + +### Feature Unification + +This command shows a graph much closer to a feature-unified graph Cargo will +build, rather than what you list in `Cargo.toml`. For instance, if you specify +the same dependency in both `[dependencies]` and `[dev-dependencies]` but with +different features on. This command may merge all features and show a `(*)` on +one of the dependency to indicate the duplicate. + +As a result, for a mostly equivalent overview of what `cargo build` does, +`cargo tree -e normal,build` is pretty close; for a mostly equivalent overview +of what `cargo test` does, `cargo tree` is pretty close. However, it doesn't +guarantee the exact equivalence to what Cargo is going to build, since a +compilation is complex and depends on lots of different factors. + +To learn more about feature unification, check out this +[dedicated section](../reference/features.html#feature-unification). + +## OPTIONS + +### Tree Options + +{{#options}} + +{{#option "`-i` _spec_" "`--invert` _spec_" }} +Show the reverse dependencies for the given package. This flag will invert +the tree and display the packages that depend on the given package. + +Note that in a workspace, by default it will only display the package's +reverse dependencies inside the tree of the workspace member in the current +directory. The `--workspace` flag can be used to extend it so that it will +show the package's reverse dependencies across the entire workspace. The `-p` +flag can be used to display the package's reverse dependencies only with the +subtree of the package given to `-p`. +{{/option}} + +{{#option "`--prune` _spec_" }} +Prune the given package from the display of the dependency tree. +{{/option}} + +{{#option "`--depth` _depth_" }} +Maximum display depth of the dependency tree. A depth of 1 displays the direct +dependencies, for example. +{{/option}} + +{{#option "`--no-dedupe`" }} +Do not de-duplicate repeated dependencies. Usually, when a package has already +displayed its dependencies, further occurrences will not re-display its +dependencies, and will include a `(*)` to indicate it has already been shown. +This flag will cause those duplicates to be repeated. +{{/option}} + +{{#option "`-d`" "`--duplicates`" }} +Show only dependencies which come in multiple versions (implies `--invert`). +When used with the `-p` flag, only shows duplicates within the subtree of the +given package. + +It can be beneficial for build times and executable sizes to avoid building +that same package multiple times. This flag can help identify the offending +packages. You can then investigate if the package that depends on the +duplicate with the older version can be updated to the newer version so that +only one instance is built. +{{/option}} + +{{#option "`-e` _kinds_" "`--edges` _kinds_" }} +The dependency kinds to display. Takes a comma separated list of values: + +- `all` --- Show all edge kinds. +- `normal` --- Show normal dependencies. +- `build` --- Show build dependencies. +- `dev` --- Show development dependencies. +- `features` --- Show features enabled by each dependency. If this is the only + kind given, then it will automatically include the other dependency kinds. +- `no-normal` --- Do not include normal dependencies. +- `no-build` --- Do not include build dependencies. +- `no-dev` --- Do not include development dependencies. +- `no-proc-macro` --- Do not include procedural macro dependencies. + +The `normal`, `build`, `dev`, and `all` dependency kinds cannot be mixed with +`no-normal`, `no-build`, or `no-dev` dependency kinds. + +The default is `normal,build,dev`. +{{/option}} + +{{#option "`--target` _triple_" }} +Filter dependencies matching the given [target triple](../appendix/glossary.html#target). +The default is the host platform. Use the value `all` to include *all* targets. +{{/option}} + +{{/options}} + +### Tree Formatting Options + +{{#options}} + +{{#option "`--charset` _charset_" }} +Chooses the character set to use for the tree. Valid values are "utf8" or +"ascii". Default is "utf8". +{{/option}} + +{{#option "`-f` _format_" "`--format` _format_" }} +Set the format string for each package. The default is "{p}". + +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. +- `{lib}` --- The name, as used in a `use` statement, of the package's library. +{{/option}} + +{{#option "`--prefix` _prefix_" }} +Sets how each line is displayed. The _prefix_ value can be one of: + +- `indent` (default) --- Shows each line indented as a tree. +- `depth` --- Show as a list, with the numeric depth printed before each entry. +- `none` --- Show as a flat list. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-features }} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Display the tree for the package in the current directory: + + cargo tree + +2. Display all the packages that depend on the `syn` package: + + cargo tree -i syn + +3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + +4. Show all packages that are built multiple times. This can happen if multiple + semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). + + cargo tree -d + +5. Explain why features are enabled for the `syn` package: + + cargo tree -e features -i syn + + The `-e features` flag is used to show features. The `-i` flag is used to + invert the graph so that it displays the packages that depend on `syn`. An + example of what this would display: + + ``` + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + ``` + + To read this graph, you can follow the chain for each feature from the root + to see why it is included. For example, the "full" feature is added by the + `rustversion` crate which is included from `myproject` (with the default + features), and `myproject` is the package selected on the command-line. All + of the other `syn` features are added by the "default" feature ("quote" is + added by "printing" and "proc-macro", both of which are default features). + + If you're having difficulty cross-referencing the de-duplicated `(*)` + entries, try with the `--no-dedupe` flag to get the full output. + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-uninstall.md b/src/doc/man/cargo-uninstall.md new file mode 100644 index 0000000..b2ebd09 --- /dev/null +++ b/src/doc/man/cargo-uninstall.md @@ -0,0 +1,63 @@ +# cargo-uninstall(1) + +## 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. + +{{> description-install-root }} + +## OPTIONS + +### Install Options + +{{#options}} + +{{#option "`-p`" "`--package` _spec_..." }} +Package to uninstall. +{{/option}} + +{{#option "`--bin` _name_..." }} +Only uninstall the binary _name_. +{{/option}} + +{{#option "`--root` _dir_" }} +Directory to uninstall packages from. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. 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.md b/src/doc/man/cargo-update.md new file mode 100644 index 0000000..e91606a --- /dev/null +++ b/src/doc/man/cargo-update.md @@ -0,0 +1,97 @@ +# cargo-update(1) + +## NAME + +cargo-update --- Update dependencies as recorded in the local lock file + +## SYNOPSIS + +`cargo update` [_options_] + +## DESCRIPTION + +This command will update dependencies in the `Cargo.lock` file to the latest +version. If the `Cargo.lock` file does not exist, it will be created with the +latest available versions. + +## OPTIONS + +### Update Options + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Update only the specified packages. This flag may be specified +multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format. + +If packages are specified with the `-p` flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions. + +If `-p` is not specified, all dependencies are updated. +{{/option}} + +{{#option "`--aggressive`" }} +When used with `-p`, dependencies of _spec_ are forced to update as well. +Cannot be used with `--precise`. +{{/option}} + +{{#option "`--precise` _precise_" }} +When used with `-p`, allows you to specify a specific version number to set +the package to. If the package comes from a git repository, this can be a git +revision (such as a SHA hash or tag). +{{/option}} + +{{#option "`-w`" "`--workspace`" }} +Attempt to update only packages defined in the workspace. Other packages +are updated only if they don't already exist in the lockfile. This +option is useful for updating `Cargo.lock` after you've changed version +numbers in `Cargo.toml`. +{{/option}} + +{{#option "`--dry-run`" }} +Displays what would be updated, but doesn't actually write the lockfile. +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} +{{> options-display }} +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Update all dependencies in the lockfile: + + cargo update + +2. Update only specific dependencies: + + cargo update -p foo -p bar + +3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}} diff --git a/src/doc/man/cargo-vendor.md b/src/doc/man/cargo-vendor.md new file mode 100644 index 0000000..b30d0d8 --- /dev/null +++ b/src/doc/man/cargo-vendor.md @@ -0,0 +1,93 @@ +# cargo-vendor(1) + +## NAME + +cargo-vendor --- Vendor all dependencies locally + +## SYNOPSIS + +`cargo vendor` [_options_] [_path_] + +## DESCRIPTION + +This cargo subcommand will vendor all crates.io and git dependencies for a +project into the specified directory at `<path>`. After this command completes +the vendor directory specified by `<path>` 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 + +{{#options}} + +{{#option "`-s` _manifest_" "`--sync` _manifest_" }} +Specify an extra `Cargo.toml` manifest to workspaces which should also be +vendored and synced to the output. May be specified multiple times. +{{/option}} + +{{#option "`--no-delete`" }} +Don't delete the "vendor" directory when vendoring, but rather keep all +existing contents of the vendor directory +{{/option}} + +{{#option "`--respect-source-config`" }} +Instead of ignoring `[source]` configuration by default in `.cargo/config.toml` +read it and use it when downloading crates from crates.io, for example +{{/option}} + +{{#option "`--versioned-dirs`" }} +Normally versions are only added to disambiguate multiple versions of the +same package. This option causes all directories in the "vendor" directory +to be versioned, which makes it easier to track the history of vendored +packages over time, and can help with the performance of re-vendoring when +only a subset of the packages have changed. +{{/option}} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Vendor all dependencies into a local "vendor" folder + + cargo vendor + +2. Vendor all dependencies into a local "third-party/vendor" folder + + cargo vendor third-party/vendor + +3. Vendor the current workspace as well as another to "vendor" + + cargo vendor -s ../path/to/Cargo.toml + +## SEE ALSO +{{man "cargo" 1}} + diff --git a/src/doc/man/cargo-verify-project.md b/src/doc/man/cargo-verify-project.md new file mode 100644 index 0000000..8b334fb --- /dev/null +++ b/src/doc/man/cargo-verify-project.md @@ -0,0 +1,58 @@ +# cargo-verify-project(1) + +## NAME + +cargo-verify-project --- Check correctness of crate manifest + +## SYNOPSIS + +`cargo verify-project` [_options_] + +## DESCRIPTION + +This command will parse the local manifest and check its validity. It emits a +JSON object with the result. A successful validation will display: + + {"success":"true"} + +An invalid workspace will display: + + {"invalid":"human-readable error message"} + +## OPTIONS + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +## EXIT STATUS + +* `0`: The workspace is OK. +* `1`: The workspace is invalid. + +## EXAMPLES + +1. Check the current workspace for errors: + + cargo verify-project + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-package" 1}} diff --git a/src/doc/man/cargo-version.md b/src/doc/man/cargo-version.md new file mode 100644 index 0000000..9bbadc9 --- /dev/null +++ b/src/doc/man/cargo-version.md @@ -0,0 +1,41 @@ +# cargo-version(1) + +## NAME + +cargo-version --- Show version information + +## SYNOPSIS + +`cargo version` [_options_] + +## DESCRIPTION + +Displays the version of Cargo. + +## OPTIONS + +{{#options}} + +{{#option "`-v`" "`--verbose`" }} +Display additional version information. +{{/option}} + +{{/options}} + +## EXAMPLES + +1. Display the version: + + cargo version + +2. The version is also available via flags: + + cargo --version + cargo -V + +3. Display extra version information: + + cargo -Vv + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-yank.md b/src/doc/man/cargo-yank.md new file mode 100644 index 0000000..8ad28ef --- /dev/null +++ b/src/doc/man/cargo-yank.md @@ -0,0 +1,71 @@ +# cargo-yank(1) + +## NAME + +cargo-yank --- Remove a pushed crate from the index + +## SYNOPSIS + +`cargo yank` [_options_] _crate_@_version_\ +`cargo yank` [_options_] `--version` _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 + +{{#options}} + +{{#option "`--vers` _version_" "`--version` _version_" }} +The version to yank or un-yank. +{{/option}} + +{{#option "`--undo`" }} +Undo a yank, putting a version back into the index. +{{/option}} + +{{> options-token }} + +{{> options-index }} + +{{> options-registry }} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Yank a crate from the index: + + cargo yank foo@1.0.7 + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-login" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo.md b/src/doc/man/cargo.md new file mode 100644 index 0000000..2d71fc4 --- /dev/null +++ b/src/doc/man/cargo.md @@ -0,0 +1,235 @@ +# cargo(1) + +## NAME + +cargo --- The Rust package manager + +## SYNOPSIS + +`cargo` [_options_] _command_ [_args_]\ +`cargo` [_options_] `--version`\ +`cargo` [_options_] `--list`\ +`cargo` [_options_] `--help`\ +`cargo` [_options_] `--explain` _code_ + +## DESCRIPTION + +This program is a package manager and build tool for the Rust language, +available at <https://rust-lang.org>. + +## 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 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 + +{{#options}} + +{{#option "`-V`" "`--version`" }} +Print version info and exit. If used with `--verbose`, prints extra +information. +{{/option}} + +{{#option "`--list`" }} +List all installed Cargo subcommands. If used with `--verbose`, prints extra +information. +{{/option}} + +{{#option "`--explain` _code_" }} +Run `rustc --explain CODE` which will print out a detailed explanation of an +error message (for example, `E0004`). +{{/option}} + +{{/options}} + +### Display Options + +{{#options}} + +{{> options-display }} + +{{/options}} + +### Manifest Options + +{{#options}} +{{> options-locked }} +{{/options}} + +{{> section-options-common }} + +{{> section-environment }} + +{{> section-exit-status }} + +## 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 [the reference](../reference/config.html) +for more information about configuration files. + +`.cargo/config.toml`\ + Cargo automatically searches for a file named `.cargo/config.toml` in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file. + +`$CARGO_HOME/credentials.toml`\ + Private authentication information for logging in to a registry. + +`$CARGO_HOME/registry/`\ + This directory contains cached downloads of the registry index and any +downloaded dependencies. + +`$CARGO_HOME/git/`\ + This directory contains cached downloads of git dependencies. + +Please note that the internal structure of the `$CARGO_HOME` directory is not +stable yet and may be subject to change. + +[rustup]: https://rust-lang.github.io/rustup/ + +## EXAMPLES + +1. Build a local package and all of its dependencies: + + cargo build + +2. Build a package with optimizations: + + cargo build --release + +3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + +4. Create a new package that builds an executable: + + cargo new foobar + +5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + +6. Learn about a command's options and usage: + + cargo help clean + +## BUGS + +See <https://github.com/rust-lang/cargo/issues> for issues. + +## SEE ALSO +{{man "rustc" 1}}, {{man "rustdoc" 1}} diff --git a/src/doc/man/generated_txt/cargo-add.txt b/src/doc/man/generated_txt/cargo-add.txt new file mode 100644 index 0000000..fdde1fe --- /dev/null +++ b/src/doc/man/generated_txt/cargo-add.txt @@ -0,0 +1,236 @@ +CARGO-ADD(1) + +NAME + cargo-add — Add dependencies to a Cargo.toml manifest file + +SYNOPSIS + cargo add [options] crate… + cargo add [options] --path path + cargo add [options] --git url [crate…] + +DESCRIPTION + This command can add or modify dependencies. + + The source for the dependency can be specified with: + + o crate@version: Fetch from a registry with a version constraint of + “version” + + o --path path: Fetch from the specified path + + o --git url: Pull from a git repo at url + + If no source is specified, then a best effort will be made to select + one, including: + + o Existing dependencies in other tables (like dev-dependencies) + + o Workspace members + + o Latest release in the registry + + When you add a package that is already present, the existing entry will + be updated with the flags specified. + + Upon successful invocation, the enabled (+) and disabled (-) features + <https://doc.rust-lang.org/cargo/reference/features.md> of the specified + dependency will be listed in the command’s output. + +OPTIONS + Source options + --git url + Git URL to add the specified crate from + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories>. + + --branch branch + Branch to use when adding from git. + + --tag tag + Tag to use when adding from git. + + --rev sha + Specific commit to use when adding from git. + + --path path + Filesystem path + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-path-dependencies> + to local crate to add. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Section options + --dev + Add as a development dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies>. + + --build + Add as a build dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies>. + + --target target + Add as a dependency to the given target platform + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies>. + +</dl> + + Dependency options + --dry-run + Don’t actually write the manifest + + --rename name + Rename + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#renaming-dependencies-in-cargotoml> + the dependency. + + --optional + Mark the dependency as optional + <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>. + + --no-optional + Mark the dependency as required + <https://doc.rust-lang.org/cargo/reference/features.html#optional-dependencies>. + + --no-default-features + Disable the default features + <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>. + + --default-features + Re-enable the default features + <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>. + + -F features, --features features + Space or comma separated list of features to activate + <https://doc.rust-lang.org/cargo/reference/features.html#dependency-features>. + When adding multiple crates, the features for a specific crate may + be enabled with package-name/feature-name syntax. This flag may be + specified multiple times, which enables all specified features. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + -p spec, --package spec + Add dependencies to only the specified package. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Add regex as a dependency + + cargo add regex + + 2. Add trybuild as a dev-dependency + + cargo add --dev trybuild + + 3. Add an older version of nom as a dependency + + cargo add nom@5 + + 4. Add support for serializing data structures to json with derives + + cargo add serde serde_json -F serde/derive + +SEE ALSO + cargo(1), cargo-remove(1) + diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt new file mode 100644 index 0000000..78eed19 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -0,0 +1,425 @@ +CARGO-BENCH(1) + +NAME + cargo-bench — Execute benchmarks of a package + +SYNOPSIS + cargo bench [options] [benchname] [-- bench-options] + +DESCRIPTION + Compile and execute benchmarks. + + The benchmark filtering argument benchname and all the arguments + following the two dashes (--) are passed to the benchmark binaries and + thus to libtest (rustc’s built in unit-test and micro-benchmarking + framework). If you are passing arguments to both Cargo and the binary, + the ones after -- go to the binary, the ones before go to Cargo. For + details about libtest’s arguments see the output of cargo bench -- + --help and check out the rustc book’s chapter on how tests work at + <https://doc.rust-lang.org/rustc/tests/index.html>. + + 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 a + special executable by linking your code with libtest. The executable + automatically runs all functions annotated with the #[bench] attribute. + Cargo passes the --bench flag to the test harness to tell it to run only + benchmarks. + + The libtest harness may be disabled by setting harness = false in the + target manifest settings, in which case your code will need to provide + its own main function to handle running benchmarks. + + Note: The #[bench] attribute + <https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html> + is currently unstable and only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html>. There + are some packages available on crates.io + <https://crates.io/keywords/benchmark> that may help with running + benchmarks on the stable channel, such as Criterion + <https://crates.io/crates/criterion>. + + By default, cargo bench uses the bench profile + <https://doc.rust-lang.org/cargo/reference/profiles.html#bench>, which + enables optimizations and disables debugging information. If you need to + debug a benchmark, you can use the --profile=dev command-line option to + switch to the dev profile. You can then run the debug-enabled benchmark + within a debugger. + +OPTIONS + Benchmark Options + --no-run + Compile, but don’t run benchmarks. + + --no-fail-fast + Run all benchmarks regardless of failure. Without this flag, Cargo + will exit after the first executable fails. The Rust test harness + will run all benchmarks within the executable to completion, this + flag only applies to the executable as a whole. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Benchmark only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Benchmark all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo bench will build the + following targets of the selected packages: + + o lib — used to link with binaries and benchmarks + + o bins (only if benchmark targets are built and required features are + available) + + o lib as a benchmark + + o bins as benchmarks + + o benchmark targets + + The default behavior can be changed by setting the bench flag for the + target in the manifest settings. Setting examples to bench = true will + build and run the example as a benchmark. Setting targets to bench = + false will stop them from being benchmarked by default. Target selection + options that take a target by name ignore the bench flag and will always + benchmark the given target. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to benchmark. This allows an integration + test to execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will benchmark only the specified + targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Benchmark the package’s library. + + --bin name… + Benchmark the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Benchmark all binary targets. + + --example name… + Benchmark the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Benchmark all example targets. + + --test name… + Benchmark the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Benchmark all targets in test mode that have the test = true + manifest flag set. By default this includes the library and binaries + built as unittests, and integration tests. Be aware that this will + also build any required dependencies, so the lib target may be built + twice (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Benchmark the specified benchmark. This flag may be specified + multiple times and supports common Unix glob patterns. + + --benches + Benchmark all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Benchmark all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Benchmark for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --profile name + Benchmark with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Benchmark the target even if the selected Rust compiler is older + than the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + By default the Rust test harness hides output from benchmark execution + to keep results readable. Benchmark output can be recovered (e.g., for + debugging) by passing --nocapture to the benchmark binaries: + + cargo bench -- --nocapture + + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + The --jobs argument affects the building of the benchmark executable but + does not affect how many threads are used when running the benchmarks. + The Rust test harness runs benchmarks serially in a single thread. + + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build and execute all the benchmarks of the current package: + + cargo bench + + 2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +SEE ALSO + cargo(1), cargo-test(1) + diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt new file mode 100644 index 0000000..8b5b778 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -0,0 +1,376 @@ +CARGO-BUILD(1) + +NAME + cargo-build — Compile the current package + +SYNOPSIS + cargo build [options] + +DESCRIPTION + Compile local packages and all of their dependencies. + +OPTIONS + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Build only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Build all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + 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. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to build. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will build only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Build the package’s library. + + --bin name… + Build the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Build all binary targets. + + --example name… + Build the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Build all example targets. + + --test name… + Build the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Build all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Build the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Build all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Build optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Build with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Build the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + --out-dir directory + Copy final artifacts to this directory. + + This option is unstable and available only on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable. See + <https://github.com/rust-lang/cargo/issues/6790> for more + information. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + --build-plan + Outputs a series of JSON messages to stdout that indicate the + commands to run the build. + + This option is unstable and available only on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable. See + <https://github.com/rust-lang/cargo/issues/5579> for more + information. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package and all of its dependencies: + + cargo build + + 2. Build with optimizations: + + cargo build --release + +SEE ALSO + cargo(1), cargo-rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt new file mode 100644 index 0000000..4946371 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -0,0 +1,361 @@ +CARGO-CHECK(1) + +NAME + cargo-check — Check the current package + +SYNOPSIS + cargo check [options] + +DESCRIPTION + Check a local package and all of its dependencies for errors. This will + essentially compile the packages without performing the final step of + code generation, which is faster than running cargo build. The compiler + will save metadata files to disk so that future runs will reuse them if + the source has not been modified. Some diagnostics and errors are only + emitted during code generation, so they inherently won’t be reported + with cargo check. + +OPTIONS + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Check only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Check all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo check will check all + binary and library targets of the selected packages. Binaries are + skipped if they have required-features that are missing. + + Passing target selection flags will check only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Check the package’s library. + + --bin name… + Check the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Check all binary targets. + + --example name… + Check the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Check all example targets. + + --test name… + Check the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Check all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Check the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Check all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Check all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Check for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Check optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Check with the given profile. + + As a special case, specifying the test profile will also enable + checking in test mode which will enable checking tests and enable + the test cfg option. See rustc tests + <https://doc.rust-lang.org/rustc/tests/index.html> for more detail. + + See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Check the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Check the local package for errors: + + cargo check + + 2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-clean.txt b/src/doc/man/generated_txt/cargo-clean.txt new file mode 100644 index 0000000..a145ed8 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-clean.txt @@ -0,0 +1,170 @@ +CARGO-CLEAN(1) + +NAME + cargo-clean — Remove generated artifacts + +SYNOPSIS + cargo clean [options] + +DESCRIPTION + Remove artifacts from the target directory that Cargo has generated in + the past. + + With no options, cargo clean will delete the entire target directory. + +OPTIONS + Package Selection + When no packages are selected, all packages and all dependencies in the + workspace are cleaned. + + -p spec…, --package spec… + Clean only the specified packages. This flag may be specified + multiple times. See cargo-pkgid(1) for the SPEC format. + + Clean Options + --doc + This option will cause cargo clean to remove only the doc directory + in the target directory. + + --release + Remove all artifacts in the release directory. + + --profile name + Remove all artifacts in the directory with the given profile name. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + --target triple + Clean for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Remove the entire target directory: + + cargo clean + + 2. Remove only the release artifacts: + + cargo clean --release + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt new file mode 100644 index 0000000..5a8b39f --- /dev/null +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -0,0 +1,323 @@ +CARGO-DOC(1) + +NAME + cargo-doc — Build a package’s documentation + +SYNOPSIS + cargo doc [options] + +DESCRIPTION + Build the documentation for the local package and all dependencies. The + output is placed in target/doc in rustdoc’s usual format. + +OPTIONS + Documentation Options + --open + Open the docs in a browser after building them. This will use your + default browser unless you define another one in the BROWSER + environment variable or use the doc.browser + <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser> + configuration option. + + --no-deps + Do not build documentation for dependencies. + + --document-private-items + Include non-public items in the documentation. This will be enabled + by default if documenting a binary target. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Document only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Document all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo doc will document all + binary and library targets of the selected package. The binary will be + skipped if its name is the same as the lib target. Binaries are skipped + if they have required-features that are missing. + + The default behavior can be changed by setting doc = false for the + target in the manifest settings. Using target selection options will + ignore the doc flag and will always document the given target. + + --lib + Document the package’s library. + + --bin name… + Document the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Document all binary targets. + + --example name… + Document the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Document all example targets. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Document optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Document with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Document the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package documentation and its dependencies and output + to target/doc. + + cargo doc + +SEE ALSO + cargo(1), cargo-rustdoc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-fetch.txt b/src/doc/man/generated_txt/cargo-fetch.txt new file mode 100644 index 0000000..820d5d5 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fetch.txt @@ -0,0 +1,151 @@ +CARGO-FETCH(1) + +NAME + cargo-fetch — Fetch dependencies of a package from the network + +SYNOPSIS + cargo fetch [options] + +DESCRIPTION + If a Cargo.lock file is available, this command will ensure that all of + the git dependencies and/or registry dependencies are downloaded and + locally available. Subsequent Cargo commands will be able to run offline + after a cargo fetch unless the lock file changes. + + If the lock file is not available, then this command will generate the + lock file before fetching the dependencies. + + If --target is not specified, then all target dependencies are fetched. + + See also the cargo-prefetch <https://crates.io/crates/cargo-prefetch> + plugin which adds a command to download popular crates. This may be + useful if you plan to use Cargo without a network with the --offline + flag. + +OPTIONS + Fetch options + --target triple + Fetch for the given architecture. The default is all architectures. + The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Fetch all dependencies: + + cargo fetch + +SEE ALSO + cargo(1), cargo-update(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt new file mode 100644 index 0000000..3c3627e --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -0,0 +1,432 @@ +CARGO-FIX(1) + +NAME + cargo-fix — Automatically fix lint warnings reported by rustc + +SYNOPSIS + cargo fix [options] + +DESCRIPTION + This Cargo subcommand will automatically take rustc’s suggestions from + diagnostics like warnings and apply them to your source code. This is + intended to help automate tasks that rustc itself already knows how to + tell you to fix! + + Executing cargo fix will under the hood execute cargo-check(1). Any + warnings applicable to your crate will be automatically fixed (if + possible) and all remaining warnings will be displayed when the check + process is finished. For example if you’d like to apply all fixes to + the current package, you can run: + + cargo fix + + 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 --features foo + + Similarly, other cfg expressions like platform-specific code will need + to pass --target to fix code for the given target. + + cargo fix --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>. + + Edition migration + The cargo fix subcommand can also be used to migrate a package from one + edition + <https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html> + to the next. The general procedure is: + + 1. Run cargo fix --edition. Consider also using the --all-features flag + if your project has multiple features. You may also want to run cargo + fix --edition multiple times with different --target flags if your + project has platform-specific code gated by cfg attributes. + + 2. Modify Cargo.toml to set the edition field + <https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field> + to the new edition. + + 3. Run your project tests to verify that everything still works. If new + warnings are issued, you may want to consider running cargo fix again + (without the --edition flag) to apply any suggestions given by the + compiler. + + And hopefully that’s it! Just keep in mind of the caveats mentioned + above that cargo fix cannot update code for inactive features or cfg + expressions. Also, in some rare cases the compiler is unable to + automatically migrate all code to the new edition, and this may require + manual changes after building with the new edition. + +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 next edition. This + will not update the edition in the Cargo.toml manifest, which must + be updated manually after cargo fix --edition has finished. + + --edition-idioms + Apply suggestions that will update code to the preferred style for + the current edition. + + --allow-no-vcs + Fix code even if a VCS was not detected. + + --allow-dirty + Fix code even if the working directory has changes. + + --allow-staged + Fix code even if the working directory has staged changes. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Fix only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Fix all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo fix will fix all + targets (--all-targets implied). Binaries are skipped if they have + required-features that are missing. + + Passing target selection flags will fix only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Fix the package’s library. + + --bin name… + Fix the specified binary. This flag may be specified multiple times + and supports common Unix glob patterns. + + --bins + Fix all binary targets. + + --example name… + Fix the specified example. This flag may be specified multiple times + and supports common Unix glob patterns. + + --examples + Fix all example targets. + + --test name… + Fix the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Fix all targets in test mode that have the test = true manifest flag + set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Fix the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Fix all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Fix all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Fix for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Fix optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Fix with the given profile. + + As a special case, specifying the test profile will also enable + checking in test mode which will enable checking tests and enable + the test cfg option. See rustc tests + <https://doc.rust-lang.org/rustc/tests/index.html> for more detail. + + See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Fix the target even if the selected Rust compiler is older than the + required Rust version as configured in the project’s rust-version + field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Apply compiler suggestions to the local package: + + cargo fix + + 2. Update a package to prepare it for the next edition: + + cargo fix --edition + + 3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +SEE ALSO + cargo(1), cargo-check(1) + diff --git a/src/doc/man/generated_txt/cargo-generate-lockfile.txt b/src/doc/man/generated_txt/cargo-generate-lockfile.txt new file mode 100644 index 0000000..94958d6 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-generate-lockfile.txt @@ -0,0 +1,126 @@ +CARGO-GENERATE-LOCKFILE(1) + +NAME + cargo-generate-lockfile — Generate the lockfile for a package + +SYNOPSIS + cargo generate-lockfile [options] + +DESCRIPTION + This command will create the Cargo.lock lockfile for the current package + or workspace. If the lockfile already exists, it will be rebuilt with + the latest available version of every package. + + See also cargo-update(1) which is also capable of creating a Cargo.lock + lockfile and has more options for controlling update behavior. + +OPTIONS + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +SEE ALSO + cargo(1), cargo-update(1) + diff --git a/src/doc/man/generated_txt/cargo-help.txt b/src/doc/man/generated_txt/cargo-help.txt new file mode 100644 index 0000000..0107ebe --- /dev/null +++ b/src/doc/man/generated_txt/cargo-help.txt @@ -0,0 +1,23 @@ +CARGO-HELP(1) + +NAME + cargo-help — Get help for a Cargo command + +SYNOPSIS + cargo help [subcommand] + +DESCRIPTION + Prints a help message for the given command. + +EXAMPLES + 1. Get help for a command: + + cargo help build + + 2. Help is also available with the --help flag: + + cargo build --help + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-init.txt b/src/doc/man/generated_txt/cargo-init.txt new file mode 100644 index 0000000..48887d6 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-init.txt @@ -0,0 +1,134 @@ +CARGO-INIT(1) + +NAME + cargo-init — Create a new Cargo package in an existing directory + +SYNOPSIS + cargo init [options] [path] + +DESCRIPTION + This command will create a new Cargo manifest in the current directory. + Give a path as an argument to create in the given directory. + + If there are typically-named Rust source files already in the directory, + those will be used. If not, then a sample src/main.rs file will be + created, or src/lib.rs if --lib is passed. + + If the directory is not already in a VCS repository, then a new + repository is created (see --vcs below). + + See cargo-new(1) for a similar command which will create a new package + in a new directory. + +OPTIONS + Init Options + --bin + Create a package with a binary target (src/main.rs). This is the + default behavior. + + --lib + Create a package with a library target (src/lib.rs). + + --edition edition + Specify the Rust edition to use. Default is 2021. Possible values: + 2015, 2018, 2021 + + --name name + Set the package name. Defaults to the directory name. + + --vcs vcs + Initialize a new VCS repository for the given version control system + (git, hg, pijul, or fossil) or do not initialize any version control + at all (none). If not specified, defaults to git or the + configuration value cargo-new.vcs, or none if already inside a VCS + repository. + + --registry registry + This sets the publish field in Cargo.toml to the given registry name + which will restrict publishing only to that registry. + + Registry names are defined in Cargo config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry defined by the registry.default + config key is used. If the default registry is not set and + --registry is not used, the publish field will not be set which + means that publishing will not be restricted. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the current directory: + + cargo init + +SEE ALSO + cargo(1), cargo-new(1) + diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt new file mode 100644 index 0000000..a66b231 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -0,0 +1,392 @@ +CARGO-INSTALL(1) + +NAME + cargo-install — Build and install a Rust binary + +SYNOPSIS + cargo install [options] crate[@version]… + cargo install [options] --path path + cargo install [options] --git url [crate…] + cargo install [options] --list + +DESCRIPTION + This command manages Cargo’s local set of installed binary crates. + Only packages which have executable [[bin]] or [[example]] targets can + be installed, and all executables are installed into the installation + root’s bin folder. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + <https://doc.rust-lang.org/cargo/reference/config.html> + + o CARGO_HOME environment variable + + o $HOME/.cargo + + There are multiple sources from which a crate can be installed. The + default location is crates.io but the --git, --path, and --registry + flags can change this source. If the source contains more than one + package (such as crates.io or a git repository with multiple crates) the + crate argument is required to indicate which crate should be installed. + + Crates from crates.io can optionally specify the version they wish to + install via the --version flags, and similarly packages from git + repositories can optionally specify the branch, tag, or revision that + should be installed. If a crate has multiple binaries, the --bin + argument can selectively install only one of them, and if you’d rather + install examples the --example argument can be used as well. + + If the package is already installed, Cargo will reinstall it if the + installed version does not appear to be up-to-date. If any of the + following values change, then Cargo will reinstall the package: + + o The package version and source. + + o The set of binary names installed. + + o The chosen features. + + o The profile (--profile). + + o The target (--target). + + Installing with --path will always build and install, unless there are + conflicting binaries from another package. The --force flag may be used + to force Cargo to always reinstall the package. + + If the source is crates.io or --git then by default the crate will be + built in a temporary target directory. To avoid this, the target + directory can be specified by setting the CARGO_TARGET_DIR environment + variable to a relative path. In particular, this can be useful for + caching build artifacts on continuous integration systems. + + Dealing with the Lockfile + 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. + + Configuration Discovery + This command operates on system or user level, not project level. This + means that the local configuration discovery + <https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure> + is ignored. Instead, the configuration discovery begins at + $CARGO_HOME/config.toml. If the package is installed with --path $PATH, + the local configuration will be used, beginning discovery at + $PATH/.cargo/config.toml. + +OPTIONS + Install Options + --vers version, --version version + Specify a version to install. This may be a version requirement + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.md>, + like ~1.2, to have Cargo select the newest version from the given + requirement. If the version does not have a requirement operator + (such as ^ or ~), then it must be in the form MAJOR.MINOR.PATCH, and + will install exactly that version; it is not treated as a caret + requirement like Cargo dependencies are. + + --git url + Git URL to install the specified crate from. + + --branch branch + Branch to use when installing from git. + + --tag tag + Tag to use when installing from git. + + --rev sha + Specific commit to use when installing from git. + + --path path + Filesystem path to local crate to install. + + --list + List all installed packages and their versions. + + -f, --force + Force overwriting existing crates or binaries. This can be used if a + package has installed a binary with the same name as another + package. This is also useful if something has changed on the system + that you want to rebuild with, such as a newer version of rustc. + + --no-track + By default, Cargo keeps track of the installed packages with a + metadata file stored in the installation root directory. This flag + tells Cargo not to use or create that file. With this flag, Cargo + will refuse to overwrite any existing files unless the --force flag + is used. This also disables Cargo’s ability to protect against + multiple concurrent invocations of Cargo installing at the same + time. + + --bin name… + Install only the specified binary. + + --bins + Install all binaries. + + --example name… + Install only the specified example. + + --examples + Install all examples. + + --root dir + Directory to install packages into. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + --index index + The URL of the registry index to use. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Install for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + a new temporary folder located in the temporary directory of the + platform. + + When using --path, by default it will use target directory in the + workspace of the local crate unless --target-dir is specified. + + --debug + Build with the dev profile instead the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Install with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Manifest Options + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Install or upgrade a package from crates.io: + + cargo install ripgrep + + 2. Install or reinstall the package in the current directory: + + cargo install --path . + + 3. View the list of installed packages: + + cargo install --list + +SEE ALSO + cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-locate-project.txt b/src/doc/man/generated_txt/cargo-locate-project.txt new file mode 100644 index 0000000..fcd76ff --- /dev/null +++ b/src/doc/man/generated_txt/cargo-locate-project.txt @@ -0,0 +1,117 @@ +CARGO-LOCATE-PROJECT(1) + +NAME + cargo-locate-project — Print a JSON representation of a Cargo.toml + file’s location + +SYNOPSIS + cargo locate-project [options] + +DESCRIPTION + This command will print a JSON object to stdout with the full path to + the manifest. The manifest is found by searching upward for a file named + Cargo.toml starting from the current working directory. + + If the project happens to be a part of a workspace, the manifest of the + project, rather than the workspace root, is output. This can be + overridden by the --workspace flag. The root workspace is found by + traversing further upward or by using the field package.workspace after + locating the manifest of a workspace member. + +OPTIONS + --workspace + Locate the Cargo.toml at the root of the workspace, as opposed to + the current workspace member. + + Display Options + --message-format fmt + The representation in which to print the project location. Valid + values: + + o json (default): JSON object with the path under the key + “root”. + + o plain: Just the path. + + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the path to the manifest based on the current directory: + + cargo locate-project + +SEE ALSO + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-login.txt b/src/doc/man/generated_txt/cargo-login.txt new file mode 100644 index 0000000..bd85053 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-login.txt @@ -0,0 +1,109 @@ +CARGO-LOGIN(1) + +NAME + cargo-login — Save an API token from the registry locally + +SYNOPSIS + cargo login [options] [token] + +DESCRIPTION + This command will save the API token to disk so that commands that + require authentication, such as cargo-publish(1), will be automatically + authenticated. The token is saved in $CARGO_HOME/credentials.toml. + CARGO_HOME defaults to .cargo in your home directory. + + If the token argument is not specified, it will be read from stdin. + + The API token for crates.io may be retrieved from + <https://crates.io/me>. + + Take care to keep the token secret, it should not be shared with anyone + else. + +OPTIONS + Login Options + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Save the API token to disk: + + cargo login + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt new file mode 100644 index 0000000..9bb09da --- /dev/null +++ b/src/doc/man/generated_txt/cargo-metadata.txt @@ -0,0 +1,439 @@ +CARGO-METADATA(1) + +NAME + cargo-metadata — Machine-readable metadata about the current package + +SYNOPSIS + cargo metadata [options] + +DESCRIPTION + Output JSON to stdout containing information about the workspace members + and resolved dependencies of the current package. + + It is recommended to include the --format-version flag to future-proof + your code to ensure the output is in the format you are expecting. + + See the cargo_metadata crate <https://crates.io/crates/cargo_metadata> + for a Rust API for reading the metadata. + +OUTPUT FORMAT + The output has the following format: + + { + /* 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)", + /* The file system path for a local path dependency. + not present if not a path dependency. + */ + "path": "/path/to/dep", + /* 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 the target should be documented by `cargo doc`. */ + "doc": true, + /* 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 <user@example.com>" + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", + /* 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 homepage value from the manifest or null if not specified. */ + "homepage": "https://rust-lang.org", + /* The documentation value from the manifest or null if not specified. */ + "documentation": "https://doc.rust-lang.org/stable/std", + /* 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 + <https://doc.rust-lang.org/cargo/appendix/glossary.html#target>. + Without this flag, the resolve includes all targets. + + Note that the dependencies listed in the “packages” array still + includes all dependencies. Each package definition is intended to be + an unaltered reproduction of the information within Cargo.toml. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Output JSON about the current package: + + cargo metadata --format-version=1 + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-new.txt b/src/doc/man/generated_txt/cargo-new.txt new file mode 100644 index 0000000..71cdfe6 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-new.txt @@ -0,0 +1,129 @@ +CARGO-NEW(1) + +NAME + cargo-new — Create a new Cargo package + +SYNOPSIS + cargo new [options] path + +DESCRIPTION + This command will create a new Cargo package in the given directory. + This includes a simple template with a Cargo.toml manifest, sample + source file, and a VCS ignore file. If the directory is not already in a + VCS repository, then a new repository is created (see --vcs below). + + See cargo-init(1) for a similar command which will create a new manifest + in an existing directory. + +OPTIONS + New Options + --bin + Create a package with a binary target (src/main.rs). This is the + default behavior. + + --lib + Create a package with a library target (src/lib.rs). + + --edition edition + Specify the Rust edition to use. Default is 2021. Possible values: + 2015, 2018, 2021 + + --name name + Set the package name. Defaults to the directory name. + + --vcs vcs + Initialize a new VCS repository for the given version control system + (git, hg, pijul, or fossil) or do not initialize any version control + at all (none). If not specified, defaults to git or the + configuration value cargo-new.vcs, or none if already inside a VCS + repository. + + --registry registry + This sets the publish field in Cargo.toml to the given registry name + which will restrict publishing only to that registry. + + Registry names are defined in Cargo config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry defined by the registry.default + config key is used. If the default registry is not set and + --registry is not used, the publish field will not be set which + means that publishing will not be restricted. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the given directory: + + cargo new foo + +SEE ALSO + cargo(1), cargo-init(1) + diff --git a/src/doc/man/generated_txt/cargo-owner.txt b/src/doc/man/generated_txt/cargo-owner.txt new file mode 100644 index 0000000..65f95f7 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-owner.txt @@ -0,0 +1,144 @@ +CARGO-OWNER(1) + +NAME + cargo-owner — Manage the owners of a crate on the registry + +SYNOPSIS + cargo owner [options] --add login [crate] + cargo owner [options] --remove login [crate] + cargo owner [options] --list [crate] + +DESCRIPTION + This command will modify the owners for a crate on the registry. Owners + of a crate can upload new versions and yank old versions. Non-team + owners can also modify the set of owners, so take care! + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + If the crate name is not specified, it will use the package name from + the current directory. + + See the reference + <https://doc.rust-lang.org/cargo/reference/publishing.html#cargo-owner> + for more information about owners and publishing. + +OPTIONS + Owner Options + -a, --add login… + Invite the given user or team as an owner. + + -r, --remove login… + Remove the given user or team as an owner. + + -l, --list + List owners of a crate. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config <https://doc.rust-lang.org/cargo/reference/config.html> + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. List owners of a package: + + cargo owner --list foo + + 2. Invite an owner to a package: + + cargo owner --add username foo + + 3. Remove an owner from a package: + + cargo owner --remove username foo + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-package.txt b/src/doc/man/generated_txt/cargo-package.txt new file mode 100644 index 0000000..c0b4312 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-package.txt @@ -0,0 +1,278 @@ +CARGO-PACKAGE(1) + +NAME + cargo-package — Assemble the local package into a distributable + tarball + +SYNOPSIS + cargo package [options] + +DESCRIPTION + This command will create a distributable, compressed .crate file with + the source code of the package in the current directory. The resulting + file will be stored in the target/package directory. This performs the + following steps: + + 1. Load and check the current workspace, performing some basic checks. + o Path dependencies are not allowed unless they have a version key. + Cargo will ignore the path key for dependencies in published + packages. dev-dependencies do not have this restriction. + + 2. Create the compressed .crate file. + o The original Cargo.toml file is rewritten and normalized. + + o [patch], [replace], and [workspace] sections are removed from the + manifest. + + o Cargo.lock is automatically included if the package contains an + executable binary or example target. cargo-install(1) will use the + packaged lock file if the --locked flag is used. + + o A .cargo_vcs_info.json file is included that contains information + about the current VCS checkout hash if available (not included + with --allow-dirty). + + 3. Extract the .crate file and build it to verify it can build. + o This will rebuild your package from scratch to ensure that it can + be built from a pristine state. The --no-verify flag can be used + to skip this step. + + 4. Check that build scripts did not modify any source files. + + The list of files included can be controlled with the include and + exclude fields in the manifest. + + See the reference + <https://doc.rust-lang.org/cargo/reference/publishing.html> for more + details about packaging and publishing. + + .cargo_vcs_info.json format + Will generate a .cargo_vcs_info.json in the following format + + { + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" + } + + path_in_vcs will be set to a repo-relative path for packages in + subdirectories of the version control repository. + +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. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Package only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Package all members in the workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Compilation Options + --target triple + Package for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a compressed .crate file of the current package: + + cargo package + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-pkgid.txt b/src/doc/man/generated_txt/cargo-pkgid.txt new file mode 100644 index 0000000..336bc76 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-pkgid.txt @@ -0,0 +1,168 @@ +CARGO-PKGID(1) + +NAME + cargo-pkgid — Print a fully qualified package specification + +SYNOPSIS + cargo pkgid [options] [spec] + +DESCRIPTION + Given a spec argument, print out the fully qualified package ID + specifier for a package or dependency in the current workspace. This + command will generate an error if spec is ambiguous as to which package + it refers to in the dependency graph. If no spec is given, then the + specifier for the local package is printed. + + This command requires that a lockfile is available and dependencies have + been fetched. + + A package specifier consists of a name, version, and source URL. You are + allowed to use partial specifiers to succinctly match a specific package + as long as it matches only one package. The format of a spec can be one + of the following: + + +-----------------+--------------------------------------------------+ + | SPEC Structure | Example SPEC | + +-----------------+--------------------------------------------------+ + | name | bitflags | + +-----------------+--------------------------------------------------+ + | name@version | bitflags@1.0.4 | + +-----------------+--------------------------------------------------+ + | url | https://github.com/rust-lang/cargo | + +-----------------+--------------------------------------------------+ + | url#version | https://github.com/rust-lang/cargo#0.33.0 | + +-----------------+--------------------------------------------------+ + | url#name | | + | | https://github.com/rust-lang/crates.io-index#bitflags | + +-----------------+--------------------------------------------------+ + | | | + | url#name:version | https://github.com/rust-lang/cargo#crates-io@0.21.0 | + +-----------------+--------------------------------------------------+ + +OPTIONS + Package Selection + -p spec, --package spec + Get the package ID for the given package instead of the current + package. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Retrieve package specification for foo package: + + cargo pkgid foo + + 2. Retrieve package specification for version 1.0.0 of foo: + + cargo pkgid foo@1.0.0 + + 3. Retrieve package specification for foo from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + + 4. Retrieve package specification for foo from a local package: + + cargo pkgid file:///path/to/local/package#foo + +SEE ALSO + cargo(1), cargo-generate-lockfile(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-publish.txt b/src/doc/man/generated_txt/cargo-publish.txt new file mode 100644 index 0000000..037083b --- /dev/null +++ b/src/doc/man/generated_txt/cargo-publish.txt @@ -0,0 +1,244 @@ +CARGO-PUBLISH(1) + +NAME + cargo-publish — Upload a package to the registry + +SYNOPSIS + cargo publish [options] + +DESCRIPTION + This command will create a distributable, compressed .crate file with + the source code of the package in the current directory and upload it to + a registry. The default registry is <https://crates.io>. This performs + the following steps: + + 1. Performs a few checks, including: + o Checks the package.publish key in the manifest for restrictions on + which registries you are allowed to publish to. + + 2. Create a .crate file by following the steps in cargo-package(1). + + 3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + See the reference + <https://doc.rust-lang.org/cargo/reference/publishing.html> for more + details about packaging and publishing. + +OPTIONS + Publish Options + --dry-run + Perform all checks without uploading. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config <https://doc.rust-lang.org/cargo/reference/config.html> + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --no-verify + Don’t verify the contents by building them. + + --allow-dirty + Allow working directories with uncommitted VCS changes to be + packaged. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to publish to. Registry names are defined in + Cargo config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, and there is a package.publish + <https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish-field> + field in Cargo.toml with a single registry, then it will publish to + that registry. Otherwise it will use the default registry, which is + defined by the registry.default + <https://doc.rust-lang.org/cargo/reference/config.html#registrydefault> + config key which defaults to crates-io. + + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to publish. See cargo-pkgid(1) for the SPEC format. + + Compilation Options + --target triple + Publish for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Publish the current package: + + cargo publish + +SEE ALSO + cargo(1), cargo-package(1), cargo-login(1) + diff --git a/src/doc/man/generated_txt/cargo-remove.txt b/src/doc/man/generated_txt/cargo-remove.txt new file mode 100644 index 0000000..5fb867a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-remove.txt @@ -0,0 +1,150 @@ +CARGO-REMOVE(1) + +NAME + cargo-remove — Remove dependencies from a Cargo.toml manifest file + +SYNOPSIS + cargo remove [options] dependency… + +DESCRIPTION + Remove one or more dependencies from a Cargo.toml manifest. + +OPTIONS + Section options + --dev + Remove as a development dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies>. + + --build + Remove as a build dependency + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies>. + + --target target + Remove as a dependency to the given target platform + <https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#platform-specific-dependencies>. + + Miscellaneous Options + --dry-run + Don’t actually write to the manifest. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Package Selection + -p spec…, --package spec… + Package to remove from. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Remove regex as a dependency + + cargo remove regex + + 2. Remove trybuild as a dev-dependency + + cargo remove --dev trybuild + + 3. Remove nom from the x86_64-pc-windows-gnu dependencies table + + cargo remove --target x86_64-pc-windows-gnu nom + +SEE ALSO + cargo(1), cargo-add(1) + diff --git a/src/doc/man/generated_txt/cargo-report.txt b/src/doc/man/generated_txt/cargo-report.txt new file mode 100644 index 0000000..f75a60c --- /dev/null +++ b/src/doc/man/generated_txt/cargo-report.txt @@ -0,0 +1,34 @@ +CARGO-REPORT(1) + +NAME + cargo-report — Generate and display various kinds of reports + +SYNOPSIS + cargo report type [options] + + DESCRIPTION + Displays a report of the given type — currently, only future-incompat + is supported + +OPTIONS + --id id + Show the report with the specified Cargo-generated id + + -p spec…, --package spec… + Only display a report for the specified package + +EXAMPLES + 1. Display the latest future-incompat report: + + cargo report future-incompat + + 2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +SEE ALSO + Future incompat report + <https://doc.rust-lang.org/cargo/reference/future-incompat-report.html> + + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt new file mode 100644 index 0000000..fc9112a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -0,0 +1,271 @@ +CARGO-RUN(1) + +NAME + cargo-run — Run the current package + +SYNOPSIS + cargo run [options] [-- args] + +DESCRIPTION + Run a binary or example of the local package. + + All the arguments following the two dashes (--) are passed to the binary + to run. If you’re passing arguments to both Cargo and the binary, the + ones after -- go to the binary, the ones before go to Cargo. + +OPTIONS + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to run. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo run will run the + binary target. If there are multiple binary targets, you must pass a + target flag to choose one. Or, the default-run field may be specified in + the [package] section of Cargo.toml to choose the name of the binary to + run by default. + + --bin name + Run the specified binary. + + --example name + Run the specified example. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Run for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Run optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Run with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Run the target even if the selected Rust compiler is older than the + required Rust version as configured in the project’s rust-version + field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package and run its main target (assuming only one + binary): + + cargo run + + 2. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt new file mode 100644 index 0000000..6082fe8 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -0,0 +1,383 @@ +CARGO-RUSTC(1) + +NAME + cargo-rustc — Compile the current package, and pass extra options to + the compiler + +SYNOPSIS + cargo rustc [options] [-- args] + +DESCRIPTION + The specified target for the current package (or package specified by -p + if provided) will be compiled along with all of its dependencies. The + specified args will all be passed to the final compiler invocation, not + any of the dependencies. Note that the compiler will still + unconditionally receive arguments such as -L, --extern, and + --crate-type, and the specified args will simply be added to the + compiler invocation. + + See <https://doc.rust-lang.org/rustc/index.html> for documentation on + rustc flags. + + This command requires that only one target is being compiled when + additional arguments are provided. If more than one target is available + for the current package the filters of --lib, --bin, etc, must be used + to select which target is compiled. + + To pass flags to all compiler processes spawned by Cargo, use the + RUSTFLAGS environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + or the build.rustflags config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + +OPTIONS + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to build. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo rustc will build all + binary and library targets of the selected package. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to build. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will build only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Build the package’s library. + + --bin name… + Build the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Build all binary targets. + + --example name… + Build the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Build all example targets. + + --test name… + Build the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Build all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Build the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Build all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Build optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Build with the given profile. + + The rustc subcommand will treat the following named profiles with + special behaviors: + + o check — Builds in the same way as the cargo-check(1) command + with the dev profile. + + o test — Builds in the same way as the cargo-test(1) command, + enabling building in test mode which will enable tests and enable + the test cfg option. See rustc tests + <https://doc.rust-lang.org/rustc/tests/index.html> for more + detail. + + o bench — Builds in the same was as the cargo-bench(1) command, + similar to the test profile. + + See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Build the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + --crate-type crate-type + Build for the given crate type. This flag accepts a comma-separated + list of 1 or more crate types, of which the allowed values are the + same as crate-type field in the manifest for configurating a Cargo + target. See crate-type field + <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#the-crate-type-field> + for possible values. + + If the manifest contains a list, and --crate-type is provided, the + command-line argument value will override what is in the manifest. + + This flag only works when building a lib or example library target. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + + 2. Try an experimental flag on the nightly compiler, such as this which + prints the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + + 3. Override crate-type field in Cargo.toml with command-line option: + + cargo rustc --lib --crate-type lib,cdylib + +SEE ALSO + cargo(1), cargo-build(1), rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt new file mode 100644 index 0000000..97b49c4 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -0,0 +1,338 @@ +CARGO-RUSTDOC(1) + +NAME + cargo-rustdoc — Build a package’s documentation, using specified + custom flags + +SYNOPSIS + cargo rustdoc [options] [-- args] + +DESCRIPTION + The specified target for the current package (or package specified by -p + if provided) will be documented with the specified args being passed to + the final rustdoc invocation. Dependencies will not be documented as + part of this command. Note that rustdoc will still unconditionally + receive arguments such as -L, --extern, and --crate-type, and the + specified args will simply be added to the rustdoc invocation. + + See <https://doc.rust-lang.org/rustdoc/index.html> for documentation on + rustdoc flags. + + This command requires that only one target is being compiled when + additional arguments are provided. If more than one target is available + for the current package the filters of --lib, --bin, etc, must be used + to select which target is compiled. + + To pass flags to all rustdoc processes spawned by Cargo, use the + RUSTDOCFLAGS environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + or the build.rustdocflags config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + +OPTIONS + Documentation Options + --open + Open the docs in a browser after building them. This will use your + default browser unless you define another one in the BROWSER + environment variable or use the doc.browser + <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser> + configuration option. + + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to document. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo rustdoc will document + all binary and library targets of the selected package. The binary will + be skipped if its name is the same as the lib target. Binaries are + skipped if they have required-features that are missing. + + Passing target selection flags will document only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Document the package’s library. + + --bin name… + Document the specified binary. This flag may be specified multiple + times and supports common Unix glob patterns. + + --bins + Document all binary targets. + + --example name… + Document the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Document all example targets. + + --test name… + Document the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Document all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Document the specified benchmark. This flag may be specified + multiple times and supports common Unix glob patterns. + + --benches + Document all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Document all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Document optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Document with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Document the target even if the selected Rust compiler is older than + the required Rust version as configured in the project’s + rust-version field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +SEE ALSO + cargo(1), cargo-doc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-search.txt b/src/doc/man/generated_txt/cargo-search.txt new file mode 100644 index 0000000..779ed57 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-search.txt @@ -0,0 +1,106 @@ +CARGO-SEARCH(1) + +NAME + cargo-search — Search packages in crates.io + +SYNOPSIS + cargo search [options] [query…] + +DESCRIPTION + This performs a textual search for crates on <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). + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Search for a package from crates.io: + + cargo search serde + +SEE ALSO + cargo(1), cargo-install(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt new file mode 100644 index 0000000..082447d --- /dev/null +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -0,0 +1,457 @@ +CARGO-TEST(1) + +NAME + cargo-test — Execute unit and integration tests of a package + +SYNOPSIS + cargo test [options] [testname] [-- test-options] + +DESCRIPTION + Compile and execute unit, integration, and documentation 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 and check + out the rustc book’s chapter on how tests work at + <https://doc.rust-lang.org/rustc/tests/index.html>. + + 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 a special + executable by linking your code with libtest. The executable + 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. + + If the package contains multiple test targets, each target compiles to a + special executable as aforementioned, and then is run serially. + + 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 + Documentation tests are also run by default, which is handled by + rustdoc. It extracts code samples from documentation comments of the + library target, and then executes them. + + Different from normal test targets, each code block compiles to a + doctest executable on the fly with rustc. These executables run in + parallel in separate processes. The compilation of a code block is in + fact a part of test function controlled by libtest, so some options such + as --jobs might not take effect. Note that this execution model of + doctests is not guaranteed and may change in the future; beware of + depending on it. + + See the rustdoc book <https://doc.rust-lang.org/rustdoc/> for more + information on writing doc tests. + +OPTIONS + Test Options + --no-run + Compile, but don’t run tests. + + --no-fail-fast + Run all tests regardless of failure. Without this flag, Cargo will + exit after the first executable fails. The Rust test harness will + run all tests within the executable to completion, this flag only + applies to the executable as a whole. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Test only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Test all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Target Selection + When no target selection options are given, cargo test will build the + following targets of the selected packages: + + o lib — used to link with binaries, examples, integration tests, and + doc tests + + o bins (only if integration tests are built and required features are + available) + + o examples — to ensure they compile + + o lib as a unit test + + o bins as unit tests + + o integration tests + + o doc tests for the lib target + + The default behavior can be changed by setting the test flag for the + target in the manifest settings. Setting examples to test = true will + build and run the example as a test. Setting targets to test = false + will stop them from being tested by default. Target selection options + that take a target by name ignore the test flag and will always test the + given target. + + Doc tests for libraries may be disabled by setting doctest = false for + the library in the manifest. + + Binary targets are automatically built if there is an integration test + or benchmark being selected to test. This allows an integration test to + execute the binary to exercise and test its behavior. The + CARGO_BIN_EXE_<name> environment variable + <https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates> + is set when the integration test is built so that it can use the env + macro <https://doc.rust-lang.org/std/macro.env.html> to locate the + executable. + + Passing target selection flags will test only the specified targets. + + Note that --bin, --example, --test and --bench flags also support common + Unix glob patterns like *, ? and []. However, to avoid your shell + accidentally expanding glob patterns before Cargo handles them, you must + use single quotes or double quotes around each glob pattern. + + --lib + Test the package’s library. + + --bin name… + Test the specified binary. This flag may be specified multiple times + and supports common Unix glob patterns. + + --bins + Test all binary targets. + + --example name… + Test the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Test all example targets. + + --test name… + Test the specified integration test. This flag may be specified + multiple times and supports common Unix glob patterns. + + --tests + Test all targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name… + Test the specified benchmark. This flag may be specified multiple + times and supports common Unix glob patterns. + + --benches + Test all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Test all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + --doc + Test only the library’s documentation. This cannot be mixed with + other target options. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Compilation Options + --target triple + Test for the given architecture. The default is the host + architecture. The general format of the triple is + <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for + a list of supported targets. This flag may be specified multiple + times. + + This may also be specified with the build.target config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + <https://doc.rust-lang.org/cargo/guide/build-cache.html> + documentation for more details. + + -r, --release + Test optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Test with the given profile. See the the reference + <https://doc.rust-lang.org/cargo/reference/profiles.html> for more + details on profiles. + + --ignore-rust-version + Test the target even if the selected Rust compiler is older than the + required Rust version as configured in the project’s rust-version + field. + + --timings=fmts + Output information how long each compilation takes, and track + concurrency information over time. Accepts an optional + comma-separated list of output formats; --timings without an + argument will default to --timings=html. Specifying an output format + (rather than the default) is unstable and requires + -Zunstable-options. Valid output formats: + + o html (unstable, requires -Zunstable-options): Write a + human-readable file cargo-timing.html to the target/cargo-timings + directory with a report of the compilation. Also write a report + to the same directory with a timestamp in the filename if you + want to look at older runs. HTML output is suitable for human + consumption only, and does not provide machine-readable timing + data. + + o json (unstable, requires -Zunstable-options): Emit + machine-readable JSON information about timing information. + + Output Options + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + target in the root of the workspace. + + Display Options + By default the Rust test harness hides output from test execution to + keep results readable. Test output can be recovered (e.g., for + debugging) by passing --nocapture to the test binaries: + + cargo test -- --nocapture + + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the “short” rendering from rustc. Cannot be used + with human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc’s default color scheme. Cannot be used with human or + short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics 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. Cannot be used with human or short. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + Miscellaneous Options + The --jobs argument affects the building of the test executable but does + not affect how many threads are used when running the tests. The Rust + test harness includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + + -j N, --jobs N + Number of parallel jobs to run. May also be specified with the + build.jobs config value + <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to + the number of logical CPUs. If negative, it sets the maximum number + of parallel jobs to the number of logical CPUs plus provided value. + Should not be 0. + + --keep-going + Build as many crates in the dependency graph as possible, rather + than aborting the build on the first one that fails to build. + Unstable, requires -Zunstable-options. + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Execute all the unit and integration tests of the current package: + + cargo test + + 2. Run only tests whose names match against a filter string: + + cargo test name_filter + + 3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +SEE ALSO + cargo(1), cargo-bench(1), types of tests + <https://doc.rust-lang.org/cargo/reference/cargo-targets.html#tests>, + how to write tests <https://doc.rust-lang.org/rustc/tests/index.html> + diff --git a/src/doc/man/generated_txt/cargo-tree.txt b/src/doc/man/generated_txt/cargo-tree.txt new file mode 100644 index 0000000..bc2993d --- /dev/null +++ b/src/doc/man/generated_txt/cargo-tree.txt @@ -0,0 +1,392 @@ +CARGO-TREE(1) + +NAME + cargo-tree — Display a tree visualization of a dependency graph + +SYNOPSIS + cargo tree [options] + +DESCRIPTION + This command will display a tree of dependencies to the terminal. An + example of a simple project that depends on the “rand” package: + + myproject v0.1.0 (/myproject) + └── rand v0.7.3 + ├── getrandom v0.1.14 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── rand_core v0.5.1 (*) + [build-dependencies] + └── cc v1.0.50 + + Packages marked with (*) have been “de-duplicated”. The dependencies + for the package have already been shown elsewhere 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. + + Feature Unification + This command shows a graph much closer to a feature-unified graph Cargo + will build, rather than what you list in Cargo.toml. For instance, if + you specify the same dependency in both [dependencies] and + [dev-dependencies] but with different features on. This command may + merge all features and show a (*) on one of the dependency to indicate + the duplicate. + + As a result, for a mostly equivalent overview of what cargo build does, + cargo tree -e normal,build is pretty close; for a mostly equivalent + overview of what cargo test does, cargo tree is pretty close. However, + it doesn’t guarantee the exact equivalence to what Cargo is going to + build, since a compilation is complex and depends on lots of different + factors. + + To learn more about feature unification, check out this dedicated + section + <https://doc.rust-lang.org/cargo/reference/features.html#feature-unification>. + +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. + + --prune spec + Prune the given package from the display of the dependency tree. + + --depth depth + Maximum display depth of the dependency tree. A depth of 1 displays + the direct dependencies, for example. + + --no-dedupe + Do not de-duplicate repeated dependencies. Usually, when a package + has already displayed its dependencies, further occurrences will not + re-display its dependencies, and will include a (*) to indicate it + has already been shown. This flag will cause those duplicates to be + repeated. + + -d, --duplicates + Show only dependencies which come in multiple versions (implies + --invert). When used with the -p flag, only shows duplicates within + the subtree of the given package. + + It can be beneficial for build times and executable sizes to avoid + building that same package multiple times. This flag can help + identify the offending packages. You can then investigate if the + package that depends on the duplicate with the older version can be + updated to the newer version so that only one instance is built. + + -e kinds, --edges kinds + The dependency kinds to display. Takes a comma separated list of + values: + + o all — Show all edge kinds. + + o normal — Show normal dependencies. + + o build — Show build dependencies. + + o dev — Show development dependencies. + + o features — Show features enabled by each dependency. If this is + the only kind given, then it will automatically include the other + dependency kinds. + + o no-normal — Do not include normal dependencies. + + o no-build — Do not include build dependencies. + + o no-dev — Do not include development dependencies. + + o no-proc-macro — Do not include procedural macro dependencies. + + The normal, build, dev, and all dependency kinds cannot be mixed + with no-normal, no-build, or no-dev dependency kinds. + + The default is normal,build,dev. + + --target triple + Filter dependencies matching the given target triple + <https://doc.rust-lang.org/cargo/appendix/glossary.html#target>. The + default is the host platform. Use the value all to include all + targets. + + Tree Formatting Options + --charset charset + Chooses the character set to use for the tree. Valid values are + “utf8” or “ascii”. Default is “utf8”. + + -f format, --format format + Set the format string for each package. The default is “{p}”. + + This is an arbitrary string which will be used to display each + package. The following strings will be replaced with the + corresponding value: + + o {p} — The package name. + + o {l} — The package license. + + o {r} — The package repository URL. + + o {f} — Comma-separated list of package features that are + enabled. + + o {lib} — The name, as used in a use statement, of the + package’s library. + + --prefix prefix + Sets how each line is displayed. The prefix value can be one of: + + o indent (default) — Shows each line indented as a tree. + + o depth — Show as a list, with the numeric depth printed before + each entry. + + o none — Show as a flat list. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec…, --package spec… + Display only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times and supports + common Unix glob patterns like *, ? and []. However, to avoid your + shell accidentally expanding glob patterns before Cargo handles + them, you must use single quotes or double quotes around each + pattern. + + --workspace + Display all members in the workspace. + + --exclude SPEC… + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times and + supports common Unix glob patterns like *, ? and []. However, to + avoid your shell accidentally expanding glob patterns before Cargo + handles them, you must use single quotes or double quotes around + each pattern. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Feature Selection + The feature flags allow you to control which features are enabled. When + no feature options are given, the default feature is activated for every + selected package. + + See the features documentation + <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> + for more details. + + -F features, --features features + Space or comma separated list of features to activate. Features of + workspace members may be enabled with package-name/feature-name + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the selected packages. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the tree for the package in the current directory: + + cargo tree + + 2. Display all the packages that depend on the syn package: + + cargo tree -i syn + + 3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + + 4. Show all packages that are built multiple times. This can happen if + multiple semver-incompatible versions appear in the tree (like 1.0.0 + and 2.0.0). + + cargo tree -d + + 5. Explain why features are enabled for the syn package: + + cargo tree -e features -i syn + + The -e features flag is used to show features. The -i flag is used to + invert the graph so that it displays the packages that depend on syn. + An example of what this would display: + + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + + To read this graph, you can follow the chain for each feature from + the root to see why it is included. For example, the “full” + feature is added by the rustversion crate which is included from + myproject (with the default features), and myproject is the package + selected on the command-line. All of the other syn features are added + by the “default” feature (“quote” is added by “printing” + and “proc-macro”, both of which are default features). + + If you’re having difficulty cross-referencing the de-duplicated (*) + entries, try with the --no-dedupe flag to get the full output. + +SEE ALSO + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-uninstall.txt b/src/doc/man/generated_txt/cargo-uninstall.txt new file mode 100644 index 0000000..a5ceb89 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-uninstall.txt @@ -0,0 +1,118 @@ +CARGO-UNINSTALL(1) + +NAME + cargo-uninstall — Remove a Rust binary + +SYNOPSIS + cargo uninstall [options] [spec…] + +DESCRIPTION + This command removes a package installed with cargo-install(1). The spec + argument is a package ID specification of the package to remove (see + cargo-pkgid(1)). + + By default all binaries are removed for a crate but the --bin and + --example flags can be used to only remove particular binaries. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + <https://doc.rust-lang.org/cargo/reference/config.html> + + o CARGO_HOME environment variable + + o $HOME/.cargo + +OPTIONS + Install Options + -p, --package spec… + Package to uninstall. + + --bin name… + Only uninstall the binary name. + + --root dir + Directory to uninstall packages from. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +SEE ALSO + cargo(1), cargo-install(1) + diff --git a/src/doc/man/generated_txt/cargo-update.txt b/src/doc/man/generated_txt/cargo-update.txt new file mode 100644 index 0000000..7b2d1aa --- /dev/null +++ b/src/doc/man/generated_txt/cargo-update.txt @@ -0,0 +1,164 @@ +CARGO-UPDATE(1) + +NAME + cargo-update — Update dependencies as recorded in the local lock file + +SYNOPSIS + cargo update [options] + +DESCRIPTION + This command will update dependencies in the Cargo.lock file to the + latest version. If the Cargo.lock file does not exist, it will be + created with the latest available versions. + +OPTIONS + Update Options + -p spec…, --package spec… + Update only the specified packages. This flag may be specified + multiple times. See cargo-pkgid(1) for the SPEC format. + + If packages are specified with the -p flag, then a conservative + update of the lockfile will be performed. This means that only the + dependency specified by SPEC will be updated. Its transitive + dependencies will be updated only if SPEC cannot be updated without + updating dependencies. All other dependencies will remain locked at + their currently recorded versions. + + If -p is not specified, all dependencies are updated. + + --aggressive + When used with -p, dependencies of spec are forced to update as + well. Cannot be used with --precise. + + --precise precise + When used with -p, allows you to specify a specific version number + to set the package to. If the package comes from a git repository, + this can be a git revision (such as a SHA hash or tag). + + -w, --workspace + Attempt to update only packages defined in the workspace. Other + packages are updated only if they don’t already exist in the + lockfile. This option is useful for updating Cargo.lock after + you’ve changed version numbers in Cargo.toml. + + --dry-run + Displays what would be updated, but doesn’t actually write the + lockfile. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Update all dependencies in the lockfile: + + cargo update + + 2. Update only specific dependencies: + + cargo update -p foo -p bar + + 3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +SEE ALSO + cargo(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-vendor.txt b/src/doc/man/generated_txt/cargo-vendor.txt new file mode 100644 index 0000000..03ceff3 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-vendor.txt @@ -0,0 +1,160 @@ +CARGO-VENDOR(1) + +NAME + cargo-vendor — Vendor all dependencies locally + +SYNOPSIS + cargo vendor [options] [path] + +DESCRIPTION + This cargo subcommand will vendor all crates.io and git dependencies for + a project into the specified directory at <path>. After this command + completes the vendor directory specified by <path> 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 an extra Cargo.toml manifest to workspaces which should also + be vendored and synced to the output. May be specified multiple + times. + + --no-delete + Don’t delete the “vendor” directory when vendoring, but rather + keep all existing contents of the vendor directory + + --respect-source-config + Instead of ignoring [source] configuration by default in + .cargo/config.toml read it and use it when downloading crates from + crates.io, for example + + --versioned-dirs + Normally versions are only added to disambiguate multiple versions + of the same package. This option causes all directories in the + “vendor” directory to be versioned, which makes it easier to + track the history of vendored packages over time, and can help with + the performance of re-vendoring when only a subset of the packages + have changed. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Vendor all dependencies into a local “vendor” folder + + cargo vendor + + 2. Vendor all dependencies into a local “third-party/vendor” folder + + cargo vendor third-party/vendor + + 3. Vendor the current workspace as well as another to “vendor” + + cargo vendor -s ../path/to/Cargo.toml + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-verify-project.txt b/src/doc/man/generated_txt/cargo-verify-project.txt new file mode 100644 index 0000000..1540d1d --- /dev/null +++ b/src/doc/man/generated_txt/cargo-verify-project.txt @@ -0,0 +1,129 @@ +CARGO-VERIFY-PROJECT(1) + +NAME + cargo-verify-project — Check correctness of crate manifest + +SYNOPSIS + cargo verify-project [options] + +DESCRIPTION + This command will parse the local manifest and check its validity. It + emits a JSON object with the result. A successful validation will + display: + + {"success":"true"} + + An invalid workspace will display: + + {"invalid":"human-readable error message"} + +OPTIONS + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: The workspace is OK. + + o 1: The workspace is invalid. + +EXAMPLES + 1. Check the current workspace for errors: + + cargo verify-project + +SEE ALSO + cargo(1), cargo-package(1) + diff --git a/src/doc/man/generated_txt/cargo-version.txt b/src/doc/man/generated_txt/cargo-version.txt new file mode 100644 index 0000000..138390a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-version.txt @@ -0,0 +1,32 @@ +CARGO-VERSION(1) + +NAME + cargo-version — Show version information + +SYNOPSIS + cargo version [options] + +DESCRIPTION + Displays the version of Cargo. + +OPTIONS + -v, --verbose + Display additional version information. + +EXAMPLES + 1. Display the version: + + cargo version + + 2. The version is also available via flags: + + cargo --version + cargo -V + + 3. Display extra version information: + + cargo -Vv + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-yank.txt b/src/doc/man/generated_txt/cargo-yank.txt new file mode 100644 index 0000000..62eb97a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-yank.txt @@ -0,0 +1,133 @@ +CARGO-YANK(1) + +NAME + cargo-yank — Remove a pushed crate from the index + +SYNOPSIS + cargo yank [options] crate@version + cargo yank [options] --version version [crate] + +DESCRIPTION + The yank command removes a previously published crate’s version from + the server’s index. This command does not delete any data, and the + crate will still be available for download via the registry’s download + link. + + Note that existing crates locked to a yanked version will still be able + to download the yanked version to use it. Cargo will, however, not allow + any new crates to be locked to any yanked version. + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + If the crate name is not specified, it will use the package name from + the current directory. + +OPTIONS + Yank Options + --vers version, --version version + The version to yank or un-yank. + + --undo + Undo a yank, putting a version back into the index. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config <https://doc.rust-lang.org/cargo/reference/config.html> + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + <https://doc.rust-lang.org/cargo/reference/config.html>. If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Yank a crate from the index: + + cargo yank foo@1.0.7 + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo.txt b/src/doc/man/generated_txt/cargo.txt new file mode 100644 index 0000000..b175a78 --- /dev/null +++ b/src/doc/man/generated_txt/cargo.txt @@ -0,0 +1,293 @@ +CARGO(1) + +NAME + cargo — The Rust package manager + +SYNOPSIS + cargo [options] command [args] + cargo [options] --version + cargo [options] --list + cargo [options] --help + cargo [options] --explain code + +DESCRIPTION + This program is a package manager and build tool for the Rust language, + available at <https://rust-lang.org>. + +COMMANDS + Build Commands + cargo-bench(1) + Execute benchmarks of a package. + + cargo-build(1) + Compile a package. + + cargo-check(1) + Check a local package and all of its dependencies for errors. + + cargo-clean(1) + Remove artifacts that Cargo has generated in the past. + + cargo-doc(1) + Build a package’s documentation. + + cargo-fetch(1) + Fetch dependencies of a package from the network. + + cargo-fix(1) + Automatically fix lint warnings reported by rustc. + + cargo-run(1) + Run a binary or example of the local package. + + cargo-rustc(1) + Compile a package, and pass extra options to the compiler. + + cargo-rustdoc(1) + Build a package’s documentation, using specified custom flags. + + cargo-test(1) + Execute unit and integration tests of a package. + + Manifest Commands + cargo-generate-lockfile(1) + Generate Cargo.lock for a project. + + cargo-locate-project(1) + Print a JSON representation of a Cargo.toml file’s location. + + cargo-metadata(1) + Output the resolved dependencies of a package in + machine-readable format. + + cargo-pkgid(1) + Print a fully qualified package specification. + + cargo-tree(1) + Display a tree visualization of a dependency graph. + + cargo-update(1) + Update dependencies as recorded in the local lock file. + + cargo-vendor(1) + Vendor all dependencies locally. + + cargo-verify-project(1) + Check correctness of crate manifest. + + Package Commands + cargo-init(1) + Create a new Cargo package in an existing directory. + + cargo-install(1) + Build and install a Rust binary. + + cargo-new(1) + Create a new Cargo package. + + cargo-search(1) + Search packages in crates.io. + + cargo-uninstall(1) + Remove a Rust binary. + + Publishing Commands + cargo-login(1) + Save an API token from the registry locally. + + cargo-owner(1) + Manage the owners of a crate on the registry. + + cargo-package(1) + Assemble the local package into a distributable tarball. + + cargo-publish(1) + Upload a package to the registry. + + cargo-yank(1) + Remove a pushed crate from the index. + + General Commands + cargo-help(1) + Display help information about Cargo. + + cargo-version(1) + Show version information. + +OPTIONS + Special Options + -V, --version + Print version info and exit. If used with --verbose, prints extra + information. + + --list + List all installed Cargo subcommands. If used with --verbose, prints + extra information. + + --explain code + Run rustc --explain CODE which will print out a detailed explanation + of an error message (for example, E0004). + + Display Options + -v, --verbose + Use verbose output. May be specified twice for “very verbose” + output which includes extra output such as dependency warnings and + build script output. May also be specified with the term.verbose + config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + -q, --quiet + Do not print cargo log messages. May also be specified with the + term.quiet config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Manifest Options + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + <https://doc.rust-lang.org/cargo/reference/config.html>. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + <https://rust-lang.github.io/rustup/overrides.html> for more + information about how toolchain overrides work. + + --config KEY=VALUE or PATH + Overrides a Cargo configuration value. The argument should be in + TOML syntax of KEY=VALUE, or provided as a path to an extra + configuration file. This flag may be specified multiple times. See + the command-line overrides section + <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides> + for more information. + + -C PATH + Changes the current working directory before executing any specified + operations. This affects things like where cargo looks by default + for the project manifest (Cargo.toml), as well as the directories + searched for discovering .cargo/config.toml, for example. + + This option is only available on the nightly channel + <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and + requires the -Z unstable-options flag to enable (see #10098 + <https://github.com/rust-lang/cargo/issues/10098>). + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + <https://doc.rust-lang.org/cargo/reference/environment-variables.html> + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +FILES + ~/.cargo/ + Default location for Cargo’s “home” directory where it + stores various files. The location can be changed with the CARGO_HOME + environment variable. + + $CARGO_HOME/bin/ + Binaries installed by cargo-install(1) will be located here. If + using rustup <https://rust-lang.github.io/rustup/>, executables + distributed with Rust are also located here. + + $CARGO_HOME/config.toml + The global configuration file. See the reference + <https://doc.rust-lang.org/cargo/reference/config.html> for more + information about configuration files. + + .cargo/config.toml + Cargo automatically searches for a file named .cargo/config.toml + in the current directory, and all parent directories. These + configuration files will be merged with the global configuration file. + + $CARGO_HOME/credentials.toml + Private authentication information for logging in to a registry. + + $CARGO_HOME/registry/ + This directory contains cached downloads of the registry index + and any downloaded dependencies. + + $CARGO_HOME/git/ + This directory contains cached downloads of git dependencies. + + Please note that the internal structure of the $CARGO_HOME directory is + not stable yet and may be subject to change. + +EXAMPLES + 1. Build a local package and all of its dependencies: + + cargo build + + 2. Build a package with optimizations: + + cargo build --release + + 3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + + 4. Create a new package that builds an executable: + + cargo new foobar + + 5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + + 6. Learn about a command’s options and usage: + + cargo help clean + +BUGS + See <https://github.com/rust-lang/cargo/issues> for issues. + +SEE ALSO + rustc(1), rustdoc(1) + 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 0000000..50cf51b --- /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 [config value](../reference/config.html) +- `CARGO_HOME` environment variable +- `$HOME/.cargo` 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 0000000..7af1813 --- /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 0000000..917dac4 --- /dev/null +++ b/src/doc/man/includes/options-display.md @@ -0,0 +1,24 @@ +{{#option "`-v`" "`--verbose`"}} +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the `term.verbose` +[config value](../reference/config.html). +{{/option}} + +{{#option "`-q`" "`--quiet`"}} +Do not print cargo log messages. +May also be specified with the `term.quiet` +[config value](../reference/config.html). +{{/option}} + +{{#option "`--color` _when_"}} +Control when colored output is used. Valid values: + +- `auto` (default): Automatically detect if color support is available on the + terminal. +- `always`: Always display colors. +- `never`: Never display colors. + +May also be specified with the `term.color` +[config value](../reference/config.html). +{{/option}} diff --git a/src/doc/man/includes/options-future-incompat.md b/src/doc/man/includes/options-future-incompat.md new file mode 100644 index 0000000..3a8a1e7 --- /dev/null +++ b/src/doc/man/includes/options-future-incompat.md @@ -0,0 +1,6 @@ +{{#option "`--future-incompat-report`"}} +Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command + +See {{man "cargo-report" 1}} +{{/option}} diff --git a/src/doc/man/includes/options-ignore-rust-version.md b/src/doc/man/includes/options-ignore-rust-version.md new file mode 100644 index 0000000..a151534 --- /dev/null +++ b/src/doc/man/includes/options-ignore-rust-version.md @@ -0,0 +1,4 @@ +{{#option "`--ignore-rust-version`"}} +{{actionverb}} the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's `rust-version` field. +{{/option}} diff --git a/src/doc/man/includes/options-index.md b/src/doc/man/includes/options-index.md new file mode 100644 index 0000000..b19b983 --- /dev/null +++ b/src/doc/man/includes/options-index.md @@ -0,0 +1,3 @@ +{{#option "`--index` _index_"}} +The URL of the registry index to use. +{{/option}} diff --git a/src/doc/man/includes/options-jobs.md b/src/doc/man/includes/options-jobs.md new file mode 100644 index 0000000..2742638 --- /dev/null +++ b/src/doc/man/includes/options-jobs.md @@ -0,0 +1,7 @@ +{{#option "`-j` _N_" "`--jobs` _N_"}} +Number of parallel jobs to run. May also be specified with the +`build.jobs` [config value](../reference/config.html). Defaults to +the number of logical CPUs. If negative, it sets the maximum number of +parallel jobs to the number of logical CPUs plus provided value. +Should not be 0. +{{/option}} diff --git a/src/doc/man/includes/options-keep-going.md b/src/doc/man/includes/options-keep-going.md new file mode 100644 index 0000000..034181c --- /dev/null +++ b/src/doc/man/includes/options-keep-going.md @@ -0,0 +1,5 @@ +{{#option "`--keep-going`"}} +Build as many crates in the dependency graph as possible, rather than aborting +the build on the first one that fails to build. Unstable, requires +`-Zunstable-options`. +{{/option}} diff --git a/src/doc/man/includes/options-locked.md b/src/doc/man/includes/options-locked.md new file mode 100644 index 0000000..c9ac952 --- /dev/null +++ b/src/doc/man/includes/options-locked.md @@ -0,0 +1,25 @@ +{{#option "`--frozen`" "`--locked`"}} +Either of these flags requires that the `Cargo.lock` file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The `--frozen` flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date. + +These may be used in environments where you want to assert that the +`Cargo.lock` file is up-to-date (such as a CI build) or want to avoid network +access. +{{/option}} + +{{#option "`--offline`"}} +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. + +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` [config value](../reference/config.html). +{{/option}} 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 0000000..b1d6eab --- /dev/null +++ b/src/doc/man/includes/options-manifest-path.md @@ -0,0 +1,4 @@ +{{#option "`--manifest-path` _path_" }} +Path to the `Cargo.toml` file. By default, Cargo searches for the +`Cargo.toml` file in the current directory or any parent directory. +{{/option}} 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 0000000..61e970a --- /dev/null +++ b/src/doc/man/includes/options-message-format.md @@ -0,0 +1,21 @@ +{{#option "`--message-format` _fmt_" }} +The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values: + +- `human` (default): Display in a human-readable text format. Conflicts with + `short` and `json`. +- `short`: Emit shorter, human-readable text messages. Conflicts with `human` + and `json`. +- `json`: Emit JSON messages to stdout. See + [the reference](../reference/external-tools.html#json-messages) + for more details. Conflicts with `human` and `short`. +- `json-diagnostic-short`: Ensure the `rendered` field of JSON messages contains + the "short" rendering from rustc. Cannot be used with `human` or `short`. +- `json-diagnostic-rendered-ansi`: Ensure the `rendered` field of JSON messages + contains embedded ANSI color codes for respecting rustc's default color + scheme. Cannot be used with `human` or `short`. +- `json-render-diagnostics`: Instruct Cargo to not include rustc diagnostics + 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. Cannot be used with `human` or `short`. +{{/option}} diff --git a/src/doc/man/includes/options-new.md b/src/doc/man/includes/options-new.md new file mode 100644 index 0000000..e9792f0 --- /dev/null +++ b/src/doc/man/includes/options-new.md @@ -0,0 +1,39 @@ +{{#options}} + +{{#option "`--bin`" }} +Create a package with a binary target (`src/main.rs`). +This is the default behavior. +{{/option}} + +{{#option "`--lib`" }} +Create a package with a library target (`src/lib.rs`). +{{/option}} + +{{#option "`--edition` _edition_" }} +Specify the Rust edition to use. Default is 2021. +Possible values: 2015, 2018, 2021 +{{/option}} + +{{#option "`--name` _name_" }} +Set the package name. Defaults to the directory name. +{{/option}} + +{{#option "`--vcs` _vcs_" }} +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to `git` or the configuration value +`cargo-new.vcs`, or `none` if already inside a VCS repository. +{{/option}} + +{{#option "`--registry` _registry_" }} +This sets the `publish` field in `Cargo.toml` to the given registry name +which will restrict publishing only to that registry. + +Registry names are defined in [Cargo config files](../reference/config.html). +If not specified, the default registry defined by the `registry.default` +config key is used. If the default registry is not set and `--registry` is not +used, the `publish` field will not be set which means that publishing will not +be restricted. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-profile-legacy-check.md b/src/doc/man/includes/options-profile-legacy-check.md new file mode 100644 index 0000000..0ec82e6 --- /dev/null +++ b/src/doc/man/includes/options-profile-legacy-check.md @@ -0,0 +1,10 @@ +{{#option "`--profile` _name_" }} +{{actionverb}} with the given profile. + +As a special case, specifying the `test` profile will also enable checking in +test mode which will enable checking tests and enable the `test` cfg option. +See [rustc tests](https://doc.rust-lang.org/rustc/tests/index.html) for more +detail. + +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} diff --git a/src/doc/man/includes/options-profile.md b/src/doc/man/includes/options-profile.md new file mode 100644 index 0000000..2452e7b --- /dev/null +++ b/src/doc/man/includes/options-profile.md @@ -0,0 +1,4 @@ +{{#option "`--profile` _name_" }} +{{actionverb}} with the given profile. +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} diff --git a/src/doc/man/includes/options-registry.md b/src/doc/man/includes/options-registry.md new file mode 100644 index 0000000..23e1706 --- /dev/null +++ b/src/doc/man/includes/options-registry.md @@ -0,0 +1,6 @@ +{{#option "`--registry` _registry_"}} +Name of the registry to use. Registry names are defined in [Cargo config +files](../reference/config.html). If not specified, the default registry is used, +which is defined by the `registry.default` config key which defaults to +`crates-io`. +{{/option}} diff --git a/src/doc/man/includes/options-release.md b/src/doc/man/includes/options-release.md new file mode 100644 index 0000000..723dbba --- /dev/null +++ b/src/doc/man/includes/options-release.md @@ -0,0 +1,4 @@ +{{#option "`-r`" "`--release`"}} +{{actionverb}} optimized artifacts with the `release` profile. +See also the `--profile` option for choosing a specific profile by name. +{{/option}} 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 0000000..3646e95 --- /dev/null +++ b/src/doc/man/includes/options-target-dir.md @@ -0,0 +1,13 @@ +{{#option "`--target-dir` _directory_"}} +Directory for all generated artifacts and intermediate files. May also be +specified with the `CARGO_TARGET_DIR` environment variable, or the +`build.target-dir` [config value](../reference/config.html). +{{#if temp-target-dir}} Defaults to a new temporary folder located in the +temporary directory of the platform. + +When using `--path`, by default it will use `target` directory in the workspace +of the local crate unless `--target-dir` +is specified. +{{else}} Defaults to `target` in the root of the workspace. +{{/if}} +{{/option}} 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 0000000..bb180f5 --- /dev/null +++ b/src/doc/man/includes/options-target-triple.md @@ -0,0 +1,16 @@ +{{#option "`--target` _triple_"}} +{{actionverb}} for the given architecture. +{{~#if target-default-to-all-arch}} The default is all architectures. +{{~else}} The default is the host architecture. +{{~/if}} The general format of the triple is +`<arch><sub>-<vendor>-<sys>-<abi>`. Run `rustc --print target-list` for a +list of supported targets. +{{~#if multitarget }} This flag may be specified multiple times. {{~/if}} + +This may also be specified with the `build.target` +[config value](../reference/config.html). + +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +[build cache](../guide/build-cache.html) documentation for more details. +{{/option}} diff --git a/src/doc/man/includes/options-targets-bin-auto-built.md b/src/doc/man/includes/options-targets-bin-auto-built.md new file mode 100644 index 0000000..c2234ab --- /dev/null +++ b/src/doc/man/includes/options-targets-bin-auto-built.md @@ -0,0 +1,8 @@ +Binary targets are automatically built if there is an integration test or +benchmark being selected to {{lower actionverb}}. This allows an integration +test to execute the binary to exercise and test its behavior. +The `CARGO_BIN_EXE_<name>` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. 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 0000000..14342ac --- /dev/null +++ b/src/doc/man/includes/options-targets-lib-bin.md @@ -0,0 +1,12 @@ +{{#option "`--lib`" }} +{{actionverb}} the package's library. +{{/option}} + +{{#option "`--bin` _name_..." }} +{{actionverb}} the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +{{/option}} + +{{#option "`--bins`" }} +{{actionverb}} all binary targets. +{{/option}} diff --git a/src/doc/man/includes/options-targets.md b/src/doc/man/includes/options-targets.md new file mode 100644 index 0000000..3332001 --- /dev/null +++ b/src/doc/man/includes/options-targets.md @@ -0,0 +1,57 @@ +Passing target selection flags will {{lower actionverb}} only the specified +targets. + +Note that `--bin`, `--example`, `--test` and `--bench` flags also +support common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your +shell accidentally expanding glob patterns before Cargo handles them, you must +use single quotes or double quotes around each glob pattern. + +{{#options}} + +{{> options-targets-lib-bin }} + +{{#option "`--example` _name_..." }} +{{actionverb}} the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +{{/option}} + +{{#option "`--examples`" }} +{{actionverb}} all example targets. +{{/option}} + +{{#option "`--test` _name_..." }} +{{actionverb}} the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +{{/option}} + +{{#option "`--tests`" }} +{{actionverb}} all targets in test mode that have the `test = true` manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the `test` flag in the +manifest settings for the target. +{{/option}} + +{{#option "`--bench` _name_..." }} +{{actionverb}} the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +{{/option}} + +{{#option "`--benches`" }} +{{actionverb}} all targets in benchmark mode that have the `bench = true` +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the `bench` flag in the +manifest settings for the target. +{{/option}} + +{{#option "`--all-targets`" }} +{{actionverb}} all targets. This is equivalent to specifying `--lib --bins +--tests --benches --examples`. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-test.md b/src/doc/man/includes/options-test.md new file mode 100644 index 0000000..1d2447e --- /dev/null +++ b/src/doc/man/includes/options-test.md @@ -0,0 +1,14 @@ +{{#options}} + +{{#option "`--no-run`" }} +Compile, but don't run {{nouns}}. +{{/option}} + +{{#option "`--no-fail-fast`" }} +Run all {{nouns}} regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all {{nouns}} +within the executable to completion, this flag only applies to the executable +as a whole. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-timings.md b/src/doc/man/includes/options-timings.md new file mode 100644 index 0000000..d4e5998 --- /dev/null +++ b/src/doc/man/includes/options-timings.md @@ -0,0 +1,16 @@ +{{#option "`--timings=`_fmts_"}} +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma-separated list of output +formats; `--timings` without an argument will default to `--timings=html`. +Specifying an output format (rather than the default) is unstable and requires +`-Zunstable-options`. Valid output formats: + +- `html` (unstable, requires `-Zunstable-options`): Write a human-readable file `cargo-timing.html` to the + `target/cargo-timings` directory with a report of the compilation. Also write + a report to the same directory with a timestamp in the filename if you want + to look at older runs. HTML output is suitable for human consumption only, + and does not provide machine-readable timing data. +- `json` (unstable, requires `-Zunstable-options`): Emit machine-readable JSON + information about timing information. +{{/option}} + diff --git a/src/doc/man/includes/options-token.md b/src/doc/man/includes/options-token.md new file mode 100644 index 0000000..855204d --- /dev/null +++ b/src/doc/man/includes/options-token.md @@ -0,0 +1,11 @@ +{{#option "`--token` _token_" }} +API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by {{man "cargo-login" 1}}). + +[Cargo config](../reference/config.html) environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the `CARGO_REGISTRY_TOKEN` environment +variable. Tokens for other registries may be specified with environment +variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name +of the registry in all capital letters. +{{/option}} diff --git a/src/doc/man/includes/section-environment.md b/src/doc/man/includes/section-environment.md new file mode 100644 index 0000000..aae5f07 --- /dev/null +++ b/src/doc/man/includes/section-environment.md @@ -0,0 +1,4 @@ +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 0000000..a812336 --- /dev/null +++ b/src/doc/man/includes/section-exit-status.md @@ -0,0 +1,4 @@ +## 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 0000000..99c13fe --- /dev/null +++ b/src/doc/man/includes/section-features.md @@ -0,0 +1,26 @@ +### Feature Selection + +The feature flags allow you to control which features are enabled. When no +feature options are given, the `default` feature is activated for every +selected package. + +See [the features documentation](../reference/features.html#command-line-feature-options) +for more details. + +{{#options}} + +{{#option "`-F` _features_" "`--features` _features_" }} +Space or comma separated list of features to activate. Features of workspace +members may be enabled with `package-name/feature-name` syntax. This flag may +be specified multiple times, which enables all specified features. +{{/option}} + +{{#option "`--all-features`" }} +Activate all available features of all selected packages. +{{/option}} + +{{#option "`--no-default-features`" }} +Do not activate the `default` feature of the selected packages. +{{/option}} + +{{/options}} 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 0000000..510db53 --- /dev/null +++ b/src/doc/man/includes/section-options-common.md @@ -0,0 +1,38 @@ +### Common Options + +{{#options}} + +{{#option "`+`_toolchain_"}} +If Cargo has been installed with rustup, and the first argument to `cargo` +begins with `+`, it will be interpreted as a rustup toolchain name (such +as `+stable` or `+nightly`). +See the [rustup documentation](https://rust-lang.github.io/rustup/overrides.html) +for more information about how toolchain overrides work. +{{/option}} + +{{#option "`--config` _KEY=VALUE_ or _PATH_"}} +Overrides a Cargo configuration value. The argument should be in TOML syntax of `KEY=VALUE`, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the [command-line overrides section](../reference/config.html#command-line-overrides) for more information. +{{/option}} + +{{#option "`-C` _PATH_"}} +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (`Cargo.toml`), as well as +the directories searched for discovering `.cargo/config.toml`, for example. + +This option is only available on the [nightly +channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) and +requires the `-Z unstable-options` flag to enable (see +[#10098](https://github.com/rust-lang/cargo/issues/10098)). +{{/option}} + +{{#option "`-h`" "`--help`"}} +Prints help information. +{{/option}} + +{{#option "`-Z` _flag_"}} +Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for details. +{{/option}} + +{{/options}} 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 0000000..4fa732d --- /dev/null +++ b/src/doc/man/includes/section-options-package.md @@ -0,0 +1,13 @@ +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +{{#options}} + +{{#option "`-p` _spec_" "`--package` _spec_" }} +The package to {{lower actionverb}}. See {{man "cargo-pkgid" 1}} for the SPEC +format. +{{/option}} + +{{/options}} 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 0000000..8d7d621 --- /dev/null +++ b/src/doc/man/includes/section-package-selection.md @@ -0,0 +1,42 @@ +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..."}} +{{actionverb}} only the specified packages. See {{man "cargo-pkgid" 1}} for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like `*`, `?` and `[]`. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +{{/option}} + +{{#option "`--workspace`" }} +{{actionverb}} all members in the workspace. +{{/option}} + +{{#unless noall}} +{{#option "`--all`" }} +Deprecated alias for `--workspace`. +{{/option}} +{{/unless}} + +{{#option "`--exclude` _SPEC_..." }} +Exclude the specified packages. Must be used in conjunction with the +`--workspace` flag. This flag may be specified multiple times and supports +common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +{{/option}} + +{{/options}} |