diff options
Diffstat (limited to 'src/doc/man/includes')
30 files changed, 447 insertions, 0 deletions
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}} |