diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:47:55 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-05-04 12:47:55 +0000 |
commit | 2aadc03ef15cb5ca5cc2af8a7c08e070742f0ac4 (patch) | |
tree | 033cc839730fda84ff08db877037977be94e5e3a /src/etc | |
parent | Initial commit. (diff) | |
download | cargo-2aadc03ef15cb5ca5cc2af8a7c08e070742f0ac4.tar.xz cargo-2aadc03ef15cb5ca5cc2af8a7c08e070742f0ac4.zip |
Adding upstream version 0.70.1+ds1.upstream/0.70.1+ds1upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
37 files changed, 10785 insertions, 0 deletions
diff --git a/src/etc/_cargo b/src/etc/_cargo new file mode 100644 index 0000000..df74c53 --- /dev/null +++ b/src/etc/_cargo @@ -0,0 +1,458 @@ +#compdef cargo + +autoload -U regexp-replace + +_cargo() { + local curcontext="$curcontext" ret=1 + local -a command_scope_spec common parallel features msgfmt triple target registry + local -a state line state_descr # These are set by _arguments + typeset -A opt_args + + common=( + '(-q --quiet)*'{-v,--verbose}'[use verbose output]' + '(-q --quiet -v --verbose)'{-q,--quiet}'[no output printed to stdout]' + '-Z+[pass unstable (nightly-only) flags to cargo]: :_cargo_unstable_flags' + '--frozen[require that Cargo.lock and cache are up-to-date]' + '--locked[require that Cargo.lock is up-to-date]' + '--color=[specify colorization option]:coloring:(auto always never)' + '(- 1 *)'{-h,--help}'[show help message]' + ) + + # leading items in parentheses are an exclusion list for the arguments following that arg + # See: http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Completion-Functions + # - => exclude all other options + # 1 => exclude positional arg 1 + # * => exclude all other args + # +blah => exclude +blah + _arguments -s -S -C $common \ + '(- 1 *)--list[list installed commands]' \ + '(- 1 *)--explain=[provide a detailed explanation of an error message]:error code' \ + '(- 1 *)'{-V,--version}'[show version information]' \ + '(+beta +nightly)+stable[use the stable toolchain]' \ + '(+stable +nightly)+beta[use the beta toolchain]' \ + '(+stable +beta)+nightly[use the nightly toolchain]' \ + '1: :_cargo_cmds' \ + '*:: :->args' + + # These flags are mutually exclusive specifiers for the scope of a command; as + # they are used in multiple places without change, they are expanded into the + # appropriate command's `_arguments` where appropriate. + command_scope_spec=( + '(--bin --example --test --lib)--bench=[specify benchmark name]: :_cargo_benchmark_names' + '(--bench --bin --test --lib)--example=[specify example name]:example name:_cargo_example_names' + '(--bench --example --test --lib)--bin=[specify binary name]:binary name' + '(--bench --bin --example --test)--lib=[specify library name]:library name' + '(--bench --bin --example --lib)--test=[specify test name]:test name' + ) + + parallel=( + '(-j --jobs)'{-j+,--jobs=}'[specify number of parallel jobs]:jobs [# of CPUs]' + '--keep-going[do not abort build on first error]' + ) + + features=( + '(--all-features)'{-F+,--features=}'[specify features to activate]:feature' + '(--features -F)--all-features[activate all available features]' + "--no-default-features[don't build the default features]" + ) + + msgfmt='--message-format=[specify error format]:error format [human]:(human json short)' + triple='--target=[specify target triple]:target triple:_cargo_target_triple' + target='--target-dir=[specify directory for all generated artifacts]:directory:_directories' + manifest='--manifest-path=[specify path to manifest]:path:_directories' + registry='--registry=[specify registry to use]:registry' + + case $state in + args) + curcontext="${curcontext%:*}-${words[1]}:" + case ${words[1]} in + add) + _arguments -s -A "^--" $common $manifest $registry \ + {-F+,--features=}'[specify features to activate]:feature' \ + "--default-features[enable the default features]" \ + "--no-default-features[don't enable the default features]" \ + "--optional[mark the dependency as optional]" \ + "--no-optional[mark the dependency as required]" \ + "--dev[add as a dev dependency]" \ + "--build[add as a build dependency]" \ + "--target=[add as a dependency to the given target platform]" \ + "--rename=[rename the dependency]" \ + "--dry-run[don't actually write the manifest]" \ + '--branch=[branch to use when adding from git]:branch' \ + '--git=[specify URL from which to add the crate]:url:_urls' \ + '--path=[local filesystem path to crate to add]: :_directories' \ + '--rev=[specific commit to use when adding from git]:commit' \ + '--tag=[tag to use when adding from git]:tag' \ + '1: :_guard "^-*" "crate name"' \ + '*:args:_default' + ;; + bench) + _arguments -s -A "^--" $common $parallel $features $msgfmt $triple $target $manifest \ + "${command_scope_spec[@]}" \ + '--all-targets[benchmark all targets]' \ + "--no-run[compile but don't run]" \ + '(-p --package)'{-p+,--package=}'[specify package to run benchmarks for]:package:_cargo_package_names' \ + '--exclude=[exclude packages from the benchmark]:spec' \ + '--no-fail-fast[run all benchmarks regardless of failure]' \ + '1: :_guard "^-*" "bench name"' \ + '*:args:_default' + ;; + + build | b) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + '--all-targets[equivalent to specifying --lib --bins --tests --benches --examples]' \ + "${command_scope_spec[@]}" \ + '(-p --package)'{-p+,--package=}'[specify package to build]:package:_cargo_package_names' \ + '--release[build in release mode]' \ + '--build-plan[output the build plan in JSON]' \ + ;; + + check | c) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + '--all-targets[equivalent to specifying --lib --bins --tests --benches --examples]' \ + "${command_scope_spec[@]}" \ + '(-p --package)'{-p+,--package=}'[specify package to check]:package:_cargo_package_names' \ + '--release[check in release mode]' \ + ;; + + clean) + _arguments -s -S $common $triple $target $manifest \ + '(-p --package)'{-p+,--package=}'[specify package to clean]:package:_cargo_package_names' \ + '--release[clean release artifacts]' \ + '--doc[clean just the documentation directory]' + ;; + + doc | d) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + '--no-deps[do not build docs for dependencies]' \ + '--document-private-items[include non-public items in the documentation]' \ + '--open[open docs in browser after the build]' \ + '(-p --package)'{-p+,--package=}'[specify package to document]:package:_cargo_package_names' \ + '--release[build artifacts in release mode, with optimizations]' \ + ;; + + fetch) + _arguments -s -S $common $triple $manifest + ;; + + fix) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + "${command_scope_spec[@]}" \ + '--broken-code[fix code even if it already has compiler errors]' \ + '--edition[fix in preparation for the next edition]' \ + '--edition-idioms[fix warnings to migrate to the idioms of an edition]' \ + '--allow-no-vcs[fix code even if a VCS was not detected]' \ + '--allow-dirty[fix code even if the working directory is dirty]' \ + '--allow-staged[fix code even if the working directory has staged changes]' + ;; + + generate-lockfile) + _arguments -s -S $common $manifest + ;; + + help) + _cargo_cmds + ;; + + init) + _arguments -s -S $common $registry \ + '--lib[use library template]' \ + '--edition=[specify edition to set for the crate generated]:edition:(2015 2018 2021)' \ + '--vcs=[initialize a new repo with a given VCS]:vcs:(git hg pijul fossil none)' \ + '--name=[set the resulting package name]:name' \ + '1:path:_directories' + ;; + + install) + _arguments -s -S $common $parallel $features $triple $registry \ + '(-f --force)'{-f,--force}'[force overwriting of existing crates or binaries]' \ + '--bin=[only install the specified binary]:binary' \ + '--branch=[branch to use when installing from git]:branch' \ + '--debug[Build in debug mode (with the "dev" profile) instead of release mode]' \ + '--example=[install the specified example instead of binaries]:example:_cargo_example_names' \ + '--git=[specify URL from which to install the crate]:url:_urls' \ + '--path=[local filesystem path to crate to install]: :_directories' \ + '--rev=[specific commit to use when installing from git]:commit' \ + '--root=[directory to install packages into]: :_directories' \ + '--tag=[tag to use when installing from git]:tag' \ + '--version=[version to install from crates.io]:version' \ + '--list[list all installed packages and their versions]' \ + '*: :_guard "^-*" "crate"' + ;; + + locate-project) + _arguments -s -S $common $manifest \ + '--message-format=[specify output representation]:output representation [json]:(json plain)' \ + '--workspace[locate Cargo.toml of the workspace root]' + ;; + + login) + _arguments -s -S $common $registry \ + '*: :_guard "^-*" "token"' + ;; + + metadata) + _arguments -s -S $common $features $manifest \ + "--no-deps[output information only about the root package and don't fetch dependencies]" \ + '--format-version=[specify format version]:version [1]:(1)' + ;; + + new) + _arguments -s -S $common $registry \ + '--lib[use library template]' \ + '--vcs:initialize a new repo with a given VCS:(git hg none)' \ + '--name=[set the resulting package name]' + ;; + + owner) + _arguments -s -S $common $registry \ + '(-a --add)'{-a,--add}'[specify name of a user or team to invite as an owner]:name' \ + '--index=[specify registry index]:index' \ + '(-l --list)'{-l,--list}'[list owners of a crate]' \ + '(-r --remove)'{-r,--remove}'[specify name of a user or team to remove as an owner]:name' \ + '--token=[specify API token to use when authenticating]:token' \ + '*: :_guard "^-*" "crate"' + ;; + + package) + _arguments -s -S $common $parallel $features $triple $target $manifest \ + '(-l --list)'{-l,--list}'[print files included in a package without making one]' \ + '--no-metadata[ignore warnings about a lack of human-usable metadata]' \ + '--allow-dirty[allow dirty working directories to be packaged]' \ + "--no-verify[don't build to verify contents]" + ;; + + pkgid) + _arguments -s -S $common $manifest \ + '(-p --package)'{-p+,--package=}'[specify package to get ID specifier for]:package:_cargo_package_names' \ + '*: :_guard "^-*" "spec"' + ;; + + publish) + _arguments -s -S $common $parallel $features $triple $target $manifest $registry \ + '--index=[specify registry index]:index' \ + '--allow-dirty[allow dirty working directories to be packaged]' \ + "--no-verify[don't verify the contents by building them]" \ + '--token=[specify token to use when uploading]:token' \ + '--dry-run[perform all checks without uploading]' + ;; + + read-manifest) + _arguments -s -S $common $manifest + ;; + + remove | rm) + _arguments -s -A "^--" $common $manifest \ + "--dev[remove as a dev dependency]" \ + "--build[remove as a build dependency]" \ + "--target=[remove as a dependency from the given target platform]" \ + "--dry-run[don't actually write the manifest]" \ + '(-p --package)'{-p+,--package=}'[package to remove from]:package:_cargo_package_names' \ + '1: :_guard "^-*" "crate name"' \ + '*:args:_default' + ;; + + run | r) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + '--example=[name of the bin target]:name:_cargo_example_names' \ + '--bin=[name of the bin target]:name' \ + '(-p --package)'{-p+,--package=}'[specify package with the target to run]:package:_cargo_package_names' \ + '--release[build in release mode]' \ + '*: :_default' + ;; + + rustc) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + '(-p --package)'{-p+,--package=}'[specify package to build]:package:_cargo_package_names' \ + '--profile=[specify profile to build the selected target for]:profile' \ + '--release[build artifacts in release mode, with optimizations]' \ + "${command_scope_spec[@]}" \ + '*: : _dispatch rustc rustc -default-' + ;; + + rustdoc) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + '--document-private-items[include non-public items in the documentation]' \ + '--open[open the docs in a browser after the operation]' \ + '(-p --package)'{-p+,--package=}'[specify package to document]:package:_cargo_package_names' \ + '--release[build artifacts in release mode, with optimizations]' \ + "${command_scope_spec[@]}" \ + '*: : _dispatch rustdoc rustdoc -default-' + ;; + + search) + _arguments -s -S $common $registry \ + '--index=[specify registry index]:index' \ + '--limit=[limit the number of results]:results [10]' \ + '*: :_guard "^-*" "query"' + ;; + + test | t) + _arguments -s -S $common $parallel $features $msgfmt $triple $target $manifest \ + '--test=[test name]: :_cargo_test_names' \ + '--no-fail-fast[run all tests regardless of failure]' \ + '--no-run[compile but do not run]' \ + '(-p --package)'{-p+,--package=}'[package to run tests for]:package:_cargo_package_names' \ + '--all[test all packages in the workspace]' \ + '--release[build artifacts in release mode, with optimizations]' \ + '1: :_cargo_test_names' \ + '(--doc --bin --example --test --bench)--lib[only test library]' \ + '(--lib --bin --example --test --bench)--doc[only test documentation]' \ + '(--lib --doc --example --test --bench)--bin=[binary name]' \ + '(--lib --doc --bin --test --bench)--example=[example name]:_cargo_example_names' \ + '(--lib --doc --bin --example --bench)--test=[test name]' \ + '(--lib --doc --bin --example --test)--bench=[benchmark name]' \ + '*: :_default' + ;; + + tree) + _arguments -s -S $common $features $triple $manifest \ + '(-p --package)'{-p+,--package=}'[package to use as the root]:package:_cargo_package_names' \ + '(-i --invert)'{-i+,--invert=}'[invert the tree for the given package]:package:_cargo_package_names' \ + '--prefix=[line prefix]:prefix:(depth indent none)' \ + '--no-dedupe[repeat shared dependencies]' \ + '(-d --duplicates)'{-d,--duplicates}'[packages with multiple versions]' \ + '--charset=[utf8 or ascii]:charset:(utf8 ascii)' \ + '(-f --format)'{-f,--format=}'[format string]:format' \ + '(-e --edges)'{-e,--edges=}'[edge kinds]:kind:(features normal build dev all no-dev no-build no-normal)' \ + ;; + + uninstall) + _arguments -s -S $common \ + '(-p --package)'{-p+,--package=}'[specify package to uninstall]:package:_cargo_package_names' \ + '--bin=[only uninstall the specified binary]:name' \ + '--root=[directory to uninstall packages from]: :_files -/' \ + '*:crate:_cargo_installed_crates -F line' + ;; + + update) + _arguments -s -S $common $manifest \ + '--aggressive=[force dependency update]' \ + "--dry-run[don't actually write the lockfile]" \ + '(-p --package)'{-p+,--package=}'[specify package to update]:package:_cargo_package_names' \ + '--precise=[update single dependency to precise release]:release' + ;; + + verify-project) + _arguments -s -S $common $manifest + ;; + + version) + _arguments -s -S $common + ;; + + yank) + _arguments -s -S $common $registry \ + '--version=[specify yank version]:version' \ + '--undo[undo a yank, putting a version back into the index]' \ + '--index=[specify registry index to yank from]:registry index' \ + '--token=[specify API token to use when authenticating]:token' \ + '*: :_guard "^-*" "crate"' + ;; + *) + # allow plugins to define their own functions + if ! _call_function ret _cargo-${words[1]}; then + # fallback on default completion for unknown commands + _default && ret=0 + fi + (( ! ret )) + ;; + esac + ;; + esac +} + +_cargo_unstable_flags() { + local flags + flags=( help ${${${(M)${(f)"$(_call_program flags cargo -Z help)"}:#*--*}/ #-- #/:}##*-Z } ) + _describe -t flags 'unstable flag' flags +} + +_cargo_installed_crates() { + local expl + _description crates expl 'crate' + compadd "$@" "$expl[@]" - ${${${(f)"$(cargo install --list)"}:# *}%% *} +} + +_cargo_cmds() { + local -a commands + # This uses Parameter Expansion Flags, which are a built-in Zsh feature. + # See more: http://zsh.sourceforge.net/Doc/Release/Expansion.html#Parameter-Expansion-Flags + # and http://zsh.sourceforge.net/Doc/Release/Expansion.html#Parameter-Expansion + # + # # How this work? + # + # First it splits the result of `cargo --list` at newline, then it removes the first line. + # Then it removes indentation (4 whitespaces) before each items. (Note the x## pattern [1]). + # Then it replaces those spaces between item and description with a `:` + # + # [1]: https://github.com/zsh-users/zsh-completions/blob/master/zsh-completions-howto.org#patterns + commands=( ${${${(M)"${(f)$(_call_program commands cargo --list)}":# *}/ ##/}/ ##/:} ) + _describe -t commands 'command' commands +} + +_cargo_target_triple() { + local -a targets + targets=( ${(f)"$(rustc --print target-list)"} ) + _describe 'target triple' targets +} + +#FIXME: Disabled until fixed +#gets package names from the manifest file +_cargo_package_names() { + _message -e packages package +} + +# Extracts the values of "name" from the array given in $1 and shows them as +# command line options for completion +_cargo_names_from_array() { + local manifest=$(cargo locate-project --message-format plain) + if [[ -z $manifest ]]; then + return 0 + fi + + local last_line + local -a names; + local in_block=false + local block_name=$1 + names=() + while read -r line; do + if [[ $last_line == "[[$block_name]]" ]]; then + in_block=true + else + if [[ $last_line =~ '\s*\[\[.*' ]]; then + in_block=false + fi + fi + + if [[ $in_block == true ]]; then + if [[ $line =~ '\s*name\s*=' ]]; then + regexp-replace line '^\s*name\s*=\s*|"' '' + names+=( "$line" ) + fi + fi + + last_line=$line + done < "$manifest" + _describe "$block_name" names + +} + +#Gets the test names from the manifest file +_cargo_test_names() { + _cargo_names_from_array "test" +} + +#Gets the bench names from the manifest file +_cargo_benchmark_names() { + _cargo_names_from_array "bench" +} + +_cargo_example_names() { + if [[ -d examples ]]; then + local -a files=(${(@f)$(echo examples/*.rs(:t:r))}) + _values 'example' "${files[@]}" + fi +} + +_cargo diff --git a/src/etc/cargo.bashcomp.sh b/src/etc/cargo.bashcomp.sh new file mode 100644 index 0000000..cb709dc --- /dev/null +++ b/src/etc/cargo.bashcomp.sh @@ -0,0 +1,287 @@ +# Required for bash versions < 4.1 +# Default bash version is 3.2 on latest macOS. See #6874 +shopt -s extglob + +command -v cargo >/dev/null 2>&1 && +_cargo() +{ + local cur prev words cword + _get_comp_words_by_ref cur prev words cword + + COMPREPLY=() + + # Skip past - and + options to find the command. + local nwords=${#words[@]} + local cmd_i cmd dd_i + for (( cmd_i=1; cmd_i<$nwords; cmd_i++ )); + do + if [[ ! "${words[$cmd_i]}" =~ ^[+-] ]]; then + cmd="${words[$cmd_i]}" + break + fi + done + # Find the location of the -- separator. + for (( dd_i=1; dd_i<$nwords-1; dd_i++ )); + do + if [[ "${words[$dd_i]}" = "--" ]]; then + break + fi + done + + local vcs='git hg none pijul fossil' + local color='auto always never' + local msg_format='human json short' + + local opt_help='-h --help' + local opt_verbose='-v --verbose' + local opt_quiet='-q --quiet' + local opt_color='--color' + local opt_common="$opt_help $opt_verbose $opt_quiet $opt_color" + local opt_pkg_spec='-p --package --all --exclude --workspace' + local opt_pkg='-p --package' + local opt_feat='-F --features --all-features --no-default-features' + local opt_mani='--manifest-path' + local opt_parallel='-j --jobs --keep-going' + local opt_force='-f --force' + local opt_sync='-s --sync' + local opt_lock='--frozen --locked --offline' + local opt_targets="--lib --bin --bins --example --examples --test --tests --bench --benches --all-targets" + + local opt___nocmd="$opt_common -V --version --list --explain" + local opt__add="$opt_common -p --package --features --default-features --no-default-features $opt_mani --optional --no-optional --rename --dry-run --path --git --branch --tag --rev --registry --dev --build --target" + local opt__bench="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock $opt_parallel $opt_targets --message-format --target --no-run --no-fail-fast --target-dir" + local opt__build="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock $opt_parallel $opt_targets --message-format --target --release --profile --target-dir" + local opt__b="$opt__build" + local opt__check="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock $opt_parallel $opt_targets --message-format --target --release --profile --target-dir" + local opt__c="$opt__check" + local opt__clean="$opt_common $opt_pkg $opt_mani $opt_lock --target --release --doc --target-dir --profile" + local opt__clippy="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock $opt_parallel $opt_targets --message-format --target --release --profile --target-dir --no-deps --fix" + local opt__doc="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock $opt_parallel --message-format --bin --bins --lib --target --open --no-deps --release --document-private-items --target-dir --profile" + local opt__d="$opt__doc" + local opt__fetch="$opt_common $opt_mani $opt_lock --target" + local opt__fix="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_parallel $opt_targets $opt_lock --release --target --message-format --broken-code --edition --edition-idioms --allow-no-vcs --allow-dirty --allow-staged --profile --target-dir" + local opt__generate_lockfile="$opt_common $opt_mani $opt_lock" + local opt__help="$opt_help" + local opt__init="$opt_common $opt_lock --bin --lib --name --vcs --edition --registry" + local opt__install="$opt_common $opt_feat $opt_parallel $opt_lock $opt_force --bin --bins --branch --debug --example --examples --git --list --path --rev --root --tag --version --registry --target --profile --no-track" + local opt__locate_project="$opt_common $opt_mani $opt_lock --message-format --workspace" + local opt__login="$opt_common $opt_lock --registry" + local opt__metadata="$opt_common $opt_feat $opt_mani $opt_lock --format-version=1 --no-deps --filter-platform" + local opt__new="$opt_common $opt_lock --vcs --bin --lib --name --edition --registry" + local opt__owner="$opt_common $opt_lock -a --add -r --remove -l --list --index --token --registry" + local opt__package="$opt_common $opt_mani $opt_feat $opt_lock $opt_parallel --allow-dirty -l --list --no-verify --no-metadata --target --target-dir" + local opt__pkgid="$opt_common $opt_mani $opt_lock $opt_pkg" + local opt__publish="$opt_common $opt_mani $opt_feat $opt_lock $opt_parallel --allow-dirty --dry-run --token --no-verify --index --registry --target --target-dir" + local opt__read_manifest="$opt_help $opt_quiet $opt_verbose $opt_mani $opt_color $opt_lock --no-deps" + local opt__remove="$opt_common $opt_pkg $opt_lock $opt_mani --dry-run --dev --build --target" + local opt__rm="$opt__remove" + local opt__report="$opt_help $opt_verbose $opt_color future-incompat future-incompatibilities" + local opt__report__future_incompat="$opt_help $opt_verbose $opt_color $opt_pkg --id" + local opt__run="$opt_common $opt_pkg $opt_feat $opt_mani $opt_lock $opt_parallel --message-format --target --bin --example --release --target-dir --profile" + local opt__r="$opt__run" + local opt__rustc="$opt_common $opt_pkg $opt_feat $opt_mani $opt_lock $opt_parallel $opt_targets -L --crate-type --extern --message-format --profile --target --release --target-dir" + local opt__rustdoc="$opt_common $opt_pkg $opt_feat $opt_mani $opt_lock $opt_parallel $opt_targets --message-format --target --release --open --target-dir --profile" + local opt__search="$opt_common $opt_lock --limit --index --registry" + local opt__test="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock $opt_parallel $opt_targets --message-format --doc --target --no-run --release --no-fail-fast --target-dir --profile" + local opt__t="$opt__test" + local opt__tree="$opt_common $opt_pkg_spec $opt_feat $opt_mani $opt_lock --target -i --invert --prefix --no-dedupe --duplicates -d --charset -f --format -e --edges" + local opt__uninstall="$opt_common $opt_lock $opt_pkg --bin --root" + local opt__update="$opt_common $opt_mani $opt_lock $opt_pkg --aggressive --precise --dry-run" + local opt__vendor="$opt_common $opt_mani $opt_lock $opt_sync --no-delete --respect-source-config --versioned-dirs" + local opt__verify_project="$opt_common $opt_mani $opt_lock" + local opt__version="$opt_common $opt_lock" + local opt__yank="$opt_common $opt_lock --version --undo --index --token --registry" + local opt__libtest="--help --include-ignored --ignored --test --bench --list --logfile --nocapture --test-threads --skip -q --quiet --exact --color --format" + + if [[ $cword -gt $dd_i ]]; then + # Completion after -- separator. + if [[ "${cmd}" = @(test|bench) ]]; then + COMPREPLY=( $( compgen -W "${opt__libtest}" -- "$cur" ) ) + else + # Fallback to filename completion, useful with `cargo run`. + _filedir + fi + elif [[ $cword -le $cmd_i ]]; then + # Completion before or at the command. + if [[ "$cur" == -* ]]; then + COMPREPLY=( $( compgen -W "${opt___nocmd}" -- "$cur" ) ) + elif [[ "$cur" == +* ]]; then + COMPREPLY=( $( compgen -W "$(_toolchains)" -- "$cur" ) ) + else + _ensure_cargo_commands_cache_filled + COMPREPLY=( $( compgen -W "$__cargo_commands_cache" -- "$cur" ) ) + fi + else + case "${prev}" in + --vcs) + COMPREPLY=( $( compgen -W "$vcs" -- "$cur" ) ) + ;; + --color) + COMPREPLY=( $( compgen -W "$color" -- "$cur" ) ) + ;; + --message-format) + COMPREPLY=( $( compgen -W "$msg_format" -- "$cur" ) ) + ;; + --manifest-path) + _filedir toml + ;; + --bin) + COMPREPLY=( $( compgen -W "$(_bin_names)" -- "$cur" ) ) + ;; + --test) + COMPREPLY=( $( compgen -W "$(_test_names)" -- "$cur" ) ) + ;; + --bench) + COMPREPLY=( $( compgen -W "$(_benchmark_names)" -- "$cur" ) ) + ;; + --example) + COMPREPLY=( $( compgen -W "$(_get_examples)" -- "$cur" ) ) + ;; + --target) + COMPREPLY=( $( compgen -W "$(_get_targets)" -- "$cur" ) ) + ;; + --target-dir|--path) + _filedir -d + ;; + help) + _ensure_cargo_commands_cache_filled + COMPREPLY=( $( compgen -W "$__cargo_commands_cache" -- "$cur" ) ) + ;; + *) + if [[ "$cmd" == "report" && "$prev" == future-incompat* ]]; then + local opt_var=opt__${cmd//-/_}__${prev//-/_} + else + local opt_var=opt__${cmd//-/_} + fi + if [[ -z "${!opt_var}" ]]; then + # Fallback to filename completion. + _filedir + else + COMPREPLY=( $( compgen -W "${!opt_var}" -- "$cur" ) ) + fi + ;; + esac + fi + + # compopt does not work in bash version 3 + + return 0 +} && +complete -F _cargo cargo + +__cargo_commands_cache= +_ensure_cargo_commands_cache_filled(){ + if [[ -z $__cargo_commands_cache ]]; then + __cargo_commands_cache="$(cargo --list 2>/dev/null | awk 'NR>1 {print $1}')" + fi +} + +_locate_manifest(){ + cargo locate-project --message-format plain 2>/dev/null +} + +# Extracts the values of "name" from the array given in $1 and shows them as +# command line options for completion +_get_names_from_array() +{ + local manifest=$(_locate_manifest) + if [[ -z $manifest ]]; then + return 0 + fi + + local last_line + local -a names + local in_block=false + local block_name=$1 + while read line + do + if [[ $last_line == "[[$block_name]]" ]]; then + in_block=true + else + if [[ $last_line =~ .*\[\[.* ]]; then + in_block=false + fi + fi + + if [[ $in_block == true ]]; then + if [[ $line =~ .*name.*\= ]]; then + line=${line##*=} + line=${line%%\"} + line=${line##*\"} + names+=($line) + fi + fi + + last_line=$line + done < $manifest + echo "${names[@]}" +} + +#Gets the bin names from the manifest file +_bin_names() +{ + _get_names_from_array "bin" +} + +#Gets the test names from the manifest file +_test_names() +{ + _get_names_from_array "test" +} + +#Gets the bench names from the manifest file +_benchmark_names() +{ + _get_names_from_array "bench" +} + +_get_examples(){ + local manifest=$(_locate_manifest) + [ -z "$manifest" ] && return 0 + + local files=("${manifest%/*}"/examples/*.rs) + local names=("${files[@]##*/}") + local names=("${names[@]%.*}") + # "*" means no examples found + if [[ "${names[@]}" != "*" ]]; then + echo "${names[@]}" + fi +} + +_get_targets(){ + local result=() + local targets=$(rustup target list) + while read line + do + if [[ "$line" =~ default|installed ]]; then + result+=("${line%% *}") + fi + done <<< "$targets" + echo "${result[@]}" +} + +_toolchains(){ + local result=() + local toolchains=$(rustup toolchain list) + local channels="nightly|beta|stable|[0-9]\.[0-9]{1,2}\.[0-9]" + local date="[0-9]{4}-[0-9]{2}-[0-9]{2}" + while read line + do + # Strip " (default)" + line=${line%% *} + if [[ "$line" =~ ^($channels)(-($date))?(-.*) ]]; then + if [[ -z ${BASH_REMATCH[3]} ]]; then + result+=("+${BASH_REMATCH[1]}") + else + # channel-date + result+=("+${BASH_REMATCH[1]}-${BASH_REMATCH[3]}") + fi + result+=("+$line") + else + result+=("+$line") + fi + done <<< "$toolchains" + echo "${result[@]}" +} + +# vim:ft=sh diff --git a/src/etc/man/cargo-add.1 b/src/etc/man/cargo-add.1 new file mode 100644 index 0000000..876680b --- /dev/null +++ b/src/etc/man/cargo-add.1 @@ -0,0 +1,317 @@ +'\" t +.TH "CARGO\-ADD" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-add \[em] Add dependencies to a Cargo.toml manifest file +.SH "SYNOPSIS" +\fBcargo add\fR [\fIoptions\fR] \fIcrate\fR\[u2026] +.br +\fBcargo add\fR [\fIoptions\fR] \fB\-\-path\fR \fIpath\fR +.br +\fBcargo add\fR [\fIoptions\fR] \fB\-\-git\fR \fIurl\fR [\fIcrate\fR\[u2026]] +.SH "DESCRIPTION" +This command can add or modify dependencies. +.sp +The source for the dependency can be specified with: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fIcrate\fR\fB@\fR\fIversion\fR: Fetch from a registry with a version constraint of \[lq]\fIversion\fR\[rq] +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB\-\-path\fR \fIpath\fR: Fetch from the specified \fIpath\fR +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB\-\-git\fR \fIurl\fR: Pull from a git repo at \fIurl\fR +.RE +.sp +If no source is specified, then a best effort will be made to select one, including: +.sp +.RS 4 +\h'-04'\(bu\h'+02'Existing dependencies in other tables (like \fBdev\-dependencies\fR) +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Workspace members +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Latest release in the registry +.RE +.sp +When you add a package that is already present, the existing entry will be updated with the flags specified. +.sp +Upon successful invocation, the enabled (\fB+\fR) and disabled (\fB\-\fR) \fIfeatures\fR <https://doc.rust\-lang.org/cargo/reference/features.md> of the specified +dependency will be listed in the command\[cq]s output. +.SH "OPTIONS" +.SS "Source options" +.sp +\fB\-\-git\fR \fIurl\fR +.RS 4 +\fIGit URL to add the specified crate from\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#specifying\-dependencies\-from\-git\-repositories>\&. +.RE +.sp +\fB\-\-branch\fR \fIbranch\fR +.RS 4 +Branch to use when adding from git. +.RE +.sp +\fB\-\-tag\fR \fItag\fR +.RS 4 +Tag to use when adding from git. +.RE +.sp +\fB\-\-rev\fR \fIsha\fR +.RS 4 +Specific commit to use when adding from git. +.RE +.sp +\fB\-\-path\fR \fIpath\fR +.RS 4 +\fIFilesystem path\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#specifying\-path\-dependencies> to local crate to add. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to use. Registry names are defined in \fICargo config +files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. +.RE +.SS "Section options" +.sp +\fB\-\-dev\fR +.RS 4 +Add as a \fIdevelopment dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#development\-dependencies>\&. +.RE +.sp +\fB\-\-build\fR +.RS 4 +Add as a \fIbuild dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#build\-dependencies>\&. +.RE +.sp +\fB\-\-target\fR \fItarget\fR +.RS 4 +Add as a dependency to the \fIgiven target platform\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#platform\-specific\-dependencies>\&. +.RE +</dl> +.SS "Dependency options" +.sp +\fB\-\-dry\-run\fR +.RS 4 +Don\[cq]t actually write the manifest +.RE +.sp +\fB\-\-rename\fR \fIname\fR +.RS 4 +\fIRename\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#renaming\-dependencies\-in\-cargotoml> the dependency. +.RE +.sp +\fB\-\-optional\fR +.RS 4 +Mark the dependency as \fIoptional\fR <https://doc.rust\-lang.org/cargo/reference/features.html#optional\-dependencies>\&. +.RE +.sp +\fB\-\-no\-optional\fR +.RS 4 +Mark the dependency as \fIrequired\fR <https://doc.rust\-lang.org/cargo/reference/features.html#optional\-dependencies>\&. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Disable the \fIdefault features\fR <https://doc.rust\-lang.org/cargo/reference/features.html#dependency\-features>\&. +.RE +.sp +\fB\-\-default\-features\fR +.RS 4 +Re\-enable the \fIdefault features\fR <https://doc.rust\-lang.org/cargo/reference/features.html#dependency\-features>\&. +.RE +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of \fIfeatures to +activate\fR <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 +\fBpackage\-name/feature\-name\fR syntax. This flag may be specified multiple times, +which enables all specified features. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +Add dependencies to only the specified package. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Add \fBregex\fR as a dependency +.sp +.RS 4 +.nf +cargo add regex +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Add \fBtrybuild\fR as a dev\-dependency +.sp +.RS 4 +.nf +cargo add \-\-dev trybuild +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Add an older version of \fBnom\fR as a dependency +.sp +.RS 4 +.nf +cargo add nom@5 +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Add support for serializing data structures to json with \fBderive\fRs +.sp +.RS 4 +.nf +cargo add serde serde_json \-F serde/derive +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-remove\fR(1) diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 new file mode 100644 index 0000000..f5ac69e --- /dev/null +++ b/src/etc/man/cargo-bench.1 @@ -0,0 +1,531 @@ +'\" t +.TH "CARGO\-BENCH" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-bench \[em] Execute benchmarks of a package +.SH "SYNOPSIS" +\fBcargo bench\fR [\fIoptions\fR] [\fIbenchname\fR] [\fB\-\-\fR \fIbench\-options\fR] +.SH "DESCRIPTION" +Compile and execute benchmarks. +.sp +The benchmark filtering argument \fIbenchname\fR and all the arguments following +the two dashes (\fB\-\-\fR) are passed to the benchmark binaries and thus to +\fIlibtest\fR (rustc\[cq]s built in unit\-test and micro\-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after \fB\-\-\fR go +to the binary, the ones before go to Cargo. For details about libtest\[cq]s +arguments see the output of \fBcargo bench \-\- \-\-help\fR and check out the rustc +book\[cq]s chapter on how tests work at +<https://doc.rust\-lang.org/rustc/tests/index.html>\&. +.sp +As an example, this will run only the benchmark named \fBfoo\fR (and skip other +similarly named benchmarks like \fBfoobar\fR): +.sp +.RS 4 +.nf +cargo bench \-\- foo \-\-exact +.fi +.RE +.sp +Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a +special executable by linking your code with libtest. The executable +automatically runs all functions annotated with the \fB#[bench]\fR attribute. +Cargo passes the \fB\-\-bench\fR flag to the test harness to tell it to run +only benchmarks. +.sp +The libtest harness may be disabled by setting \fBharness = false\fR in the target +manifest settings, in which case your code will need to provide its own \fBmain\fR +function to handle running benchmarks. +.RS 3 +.ll -5 +.sp +\fBNote\fR: The +\fI\f(BI#[bench]\fI attribute\fR <https://doc.rust\-lang.org/nightly/unstable\-book/library\-features/test.html> +is currently unstable and only available on the +\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>\&. +There are some packages available on +\fIcrates.io\fR <https://crates.io/keywords/benchmark> that may help with +running benchmarks on the stable channel, such as +\fICriterion\fR <https://crates.io/crates/criterion>\&. +.br +.RE +.ll +.sp +By default, \fBcargo bench\fR uses the \fI\f(BIbench\fI profile\fR <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 \fB\-\-profile=dev\fR command\-line option to switch to +the dev profile. You can then run the debug\-enabled benchmark within a +debugger. +.SH "OPTIONS" +.SS "Benchmark Options" +.sp +\fB\-\-no\-run\fR +.RS 4 +Compile, but don\[cq]t run benchmarks. +.RE +.sp +\fB\-\-no\-fail\-fast\fR +.RS 4 +Run all benchmarks regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all benchmarks +within the executable to completion, this flag only applies to the executable +as a whole. +.RE +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Benchmark only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Benchmark all members in the workspace. +.RE +.sp +\fB\-\-all\fR +.RS 4 +Deprecated alias for \fB\-\-workspace\fR\&. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo bench\fR will build the +following targets of the selected packages: +.sp +.RS 4 +\h'-04'\(bu\h'+02'lib \[em] used to link with binaries and benchmarks +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'bins (only if benchmark targets are built and required features are +available) +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'lib as a benchmark +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'bins as benchmarks +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'benchmark targets +.RE +.sp +The default behavior can be changed by setting the \fBbench\fR flag for the target +in the manifest settings. Setting examples to \fBbench = true\fR will build and +run the example as a benchmark. Setting targets to \fBbench = false\fR will stop +them from being benchmarked by default. Target selection options that take a +target by name ignore the \fBbench\fR flag and will always benchmark the given +target. +.sp +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 \fBCARGO_BIN_EXE_<name>\fR +\fIenvironment variable\fR <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 +\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the +executable. +.sp +Passing target selection flags will benchmark only the specified +targets. +.sp +Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also +support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. 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. +.sp +\fB\-\-lib\fR +.RS 4 +Benchmark the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Benchmark the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Benchmark all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Benchmark the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Benchmark all example targets. +.RE +.sp +\fB\-\-test\fR \fIname\fR\[u2026] +.RS 4 +Benchmark the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-tests\fR +.RS 4 +Benchmark all targets in test mode that have the \fBtest = true\fR manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the \fBtest\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-bench\fR \fIname\fR\[u2026] +.RS 4 +Benchmark the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-benches\fR +.RS 4 +Benchmark all targets in benchmark mode that have the \fBbench = true\fR +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the \fBbench\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-all\-targets\fR +.RS 4 +Benchmark all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Benchmark for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Benchmark with the given profile. +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Benchmark the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "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 \fB\-\-nocapture\fR to the benchmark binaries: +.sp +.RS 4 +.nf +cargo bench \-\- \-\-nocapture +.fi +.RE +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +The \fB\-\-jobs\fR argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread. +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Build and execute all the benchmarks of the current package: +.sp +.RS 4 +.nf +cargo bench +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Run only a specific benchmark within a specific benchmark target: +.sp +.RS 4 +.nf +cargo bench \-\-bench bench_name \-\- modname::some_benchmark +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-test\fR(1) diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 new file mode 100644 index 0000000..3fb5889 --- /dev/null +++ b/src/etc/man/cargo-build.1 @@ -0,0 +1,466 @@ +'\" t +.TH "CARGO\-BUILD" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-build \[em] Compile the current package +.SH "SYNOPSIS" +\fBcargo build\fR [\fIoptions\fR] +.SH "DESCRIPTION" +Compile local packages and all of their dependencies. +.SH "OPTIONS" +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Build only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Build all members in the workspace. +.RE +.sp +\fB\-\-all\fR +.RS 4 +Deprecated alias for \fB\-\-workspace\fR\&. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo build\fR will build all +binary and library targets of the selected packages. Binaries are skipped if +they have \fBrequired\-features\fR that are missing. +.sp +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 \fBCARGO_BIN_EXE_<name>\fR +\fIenvironment variable\fR <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 +\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the +executable. +.sp +Passing target selection flags will build only the specified +targets. +.sp +Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also +support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. 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. +.sp +\fB\-\-lib\fR +.RS 4 +Build the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Build the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Build all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Build the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Build all example targets. +.RE +.sp +\fB\-\-test\fR \fIname\fR\[u2026] +.RS 4 +Build the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-tests\fR +.RS 4 +Build all targets in test mode that have the \fBtest = true\fR manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the \fBtest\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-bench\fR \fIname\fR\[u2026] +.RS 4 +Build the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-benches\fR +.RS 4 +Build all targets in benchmark mode that have the \fBbench = true\fR +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the \fBbench\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-all\-targets\fR +.RS 4 +Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Build for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Build optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Build with the given profile. +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Build the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.sp +\fB\-\-out\-dir\fR \fIdirectory\fR +.RS 4 +Copy final artifacts to this directory. +.sp +This option is unstable and available only on the +\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> +and requires the \fB\-Z unstable\-options\fR flag to enable. +See <https://github.com/rust\-lang/cargo/issues/6790> for more information. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.sp +\fB\-\-build\-plan\fR +.RS 4 +Outputs a series of JSON messages to stdout that indicate the commands to run +the build. +.sp +This option is unstable and available only on the +\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> +and requires the \fB\-Z unstable\-options\fR flag to enable. +See <https://github.com/rust\-lang/cargo/issues/5579> for more information. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.sp +\fB\-\-future\-incompat\-report\fR +.RS 4 +Displays a future\-incompat report for any future\-incompatible warnings +produced during execution of this command +.sp +See \fBcargo\-report\fR(1) +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Build the local package and all of its dependencies: +.sp +.RS 4 +.nf +cargo build +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Build with optimizations: +.sp +.RS 4 +.nf +cargo build \-\-release +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-rustc\fR(1) diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 new file mode 100644 index 0000000..cc78caf --- /dev/null +++ b/src/etc/man/cargo-check.1 @@ -0,0 +1,447 @@ +'\" t +.TH "CARGO\-CHECK" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-check \[em] Check the current package +.SH "SYNOPSIS" +\fBcargo check\fR [\fIoptions\fR] +.SH "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 \fBcargo build\fR\&. The compiler will save +metadata files to disk so that future runs will reuse them if the source has +not been modified. Some diagnostics and errors are only emitted during code +generation, so they inherently won\[cq]t be reported with \fBcargo check\fR\&. +.SH "OPTIONS" +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Check only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Check all members in the workspace. +.RE +.sp +\fB\-\-all\fR +.RS 4 +Deprecated alias for \fB\-\-workspace\fR\&. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo check\fR will check all +binary and library targets of the selected packages. Binaries are skipped if +they have \fBrequired\-features\fR that are missing. +.sp +Passing target selection flags will check only the specified +targets. +.sp +Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also +support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. 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. +.sp +\fB\-\-lib\fR +.RS 4 +Check the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Check the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Check all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Check the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Check all example targets. +.RE +.sp +\fB\-\-test\fR \fIname\fR\[u2026] +.RS 4 +Check the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-tests\fR +.RS 4 +Check all targets in test mode that have the \fBtest = true\fR manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the \fBtest\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-bench\fR \fIname\fR\[u2026] +.RS 4 +Check the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-benches\fR +.RS 4 +Check all targets in benchmark mode that have the \fBbench = true\fR +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the \fBbench\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-all\-targets\fR +.RS 4 +Check all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Check for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Check optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Check with the given profile. +.sp +As a special case, specifying the \fBtest\fR profile will also enable checking in +test mode which will enable checking tests and enable the \fBtest\fR cfg option. +See \fIrustc tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html> for more +detail. +.sp +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Check the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.sp +\fB\-\-future\-incompat\-report\fR +.RS 4 +Displays a future\-incompat report for any future\-incompatible warnings +produced during execution of this command +.sp +See \fBcargo\-report\fR(1) +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Check the local package for errors: +.sp +.RS 4 +.nf +cargo check +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Check all targets, including unit tests: +.sp +.RS 4 +.nf +cargo check \-\-all\-targets \-\-profile=test +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-clean.1 b/src/etc/man/cargo-clean.1 new file mode 100644 index 0000000..f177007 --- /dev/null +++ b/src/etc/man/cargo-clean.1 @@ -0,0 +1,214 @@ +'\" t +.TH "CARGO\-CLEAN" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-clean \[em] Remove generated artifacts +.SH "SYNOPSIS" +\fBcargo clean\fR [\fIoptions\fR] +.SH "DESCRIPTION" +Remove artifacts from the target directory that Cargo has generated in the +past. +.sp +With no options, \fBcargo clean\fR will delete the entire target directory. +.SH "OPTIONS" +.SS "Package Selection" +When no packages are selected, all packages and all dependencies in the +workspace are cleaned. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Clean only the specified packages. This flag may be specified +multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format. +.RE +.SS "Clean Options" +.sp +\fB\-\-doc\fR +.RS 4 +This option will cause \fBcargo clean\fR to remove only the \fBdoc\fR directory in +the target directory. +.RE +.sp +\fB\-\-release\fR +.RS 4 +Remove all artifacts in the \fBrelease\fR directory. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Remove all artifacts in the directory with the given profile name. +.RE +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Clean for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Remove the entire target directory: +.sp +.RS 4 +.nf +cargo clean +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Remove only the release artifacts: +.sp +.RS 4 +.nf +cargo clean \-\-release +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 new file mode 100644 index 0000000..599f521 --- /dev/null +++ b/src/etc/man/cargo-doc.1 @@ -0,0 +1,397 @@ +'\" t +.TH "CARGO\-DOC" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-doc \[em] Build a package\[cq]s documentation +.SH "SYNOPSIS" +\fBcargo doc\fR [\fIoptions\fR] +.SH "DESCRIPTION" +Build the documentation for the local package and all dependencies. The output +is placed in \fBtarget/doc\fR in rustdoc\[cq]s usual format. +.SH "OPTIONS" +.SS "Documentation Options" +.sp +\fB\-\-open\fR +.RS 4 +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the \fBBROWSER\fR environment variable +or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> configuration +option. +.RE +.sp +\fB\-\-no\-deps\fR +.RS 4 +Do not build documentation for dependencies. +.RE +.sp +\fB\-\-document\-private\-items\fR +.RS 4 +Include non\-public items in the documentation. This will be enabled by default if documenting a binary target. +.RE +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Document only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Document all members in the workspace. +.RE +.sp +\fB\-\-all\fR +.RS 4 +Deprecated alias for \fB\-\-workspace\fR\&. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo doc\fR will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +\fBrequired\-features\fR that are missing. +.sp +The default behavior can be changed by setting \fBdoc = false\fR for the target in +the manifest settings. Using target selection options will ignore the \fBdoc\fR +flag and will always document the given target. +.sp +\fB\-\-lib\fR +.RS 4 +Document the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Document the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Document all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Document the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Document all example targets. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Document for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Document optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Document with the given profile. +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Document the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Build the local package documentation and its dependencies and output to +\fBtarget/doc\fR\&. +.sp +.RS 4 +.nf +cargo doc +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-rustdoc\fR(1), \fBrustdoc\fR(1) diff --git a/src/etc/man/cargo-fetch.1 b/src/etc/man/cargo-fetch.1 new file mode 100644 index 0000000..e2c162b --- /dev/null +++ b/src/etc/man/cargo-fetch.1 @@ -0,0 +1,178 @@ +'\" t +.TH "CARGO\-FETCH" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-fetch \[em] Fetch dependencies of a package from the network +.SH "SYNOPSIS" +\fBcargo fetch\fR [\fIoptions\fR] +.SH "DESCRIPTION" +If a \fBCargo.lock\fR file is available, this command will ensure that all of the +git dependencies and/or registry dependencies are downloaded and locally +available. Subsequent Cargo commands will be able to run offline after a \fBcargo fetch\fR unless the lock file changes. +.sp +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. +.sp +If \fB\-\-target\fR is not specified, then all target dependencies are fetched. +.sp +See also the \fIcargo\-prefetch\fR <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 \fB\-\-offline\fR flag. +.SH "OPTIONS" +.SS "Fetch options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Fetch for the given architecture. The default is all architectures. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Fetch all dependencies: +.sp +.RS 4 +.nf +cargo fetch +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-update\fR(1), \fBcargo\-generate\-lockfile\fR(1) diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 new file mode 100644 index 0000000..6ae1963 --- /dev/null +++ b/src/etc/man/cargo-fix.1 @@ -0,0 +1,544 @@ +'\" t +.TH "CARGO\-FIX" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-fix \[em] Automatically fix lint warnings reported by rustc +.SH "SYNOPSIS" +\fBcargo fix\fR [\fIoptions\fR] +.SH "DESCRIPTION" +This Cargo subcommand will automatically take rustc\[cq]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! +.sp +Executing \fBcargo fix\fR will under the hood execute \fBcargo\-check\fR(1). Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you\[cq]d like to apply all fixes to the current package, you can run: +.sp +.RS 4 +.nf +cargo fix +.fi +.RE +.sp +which behaves the same as \fBcargo check \-\-all\-targets\fR\&. +.sp +\fBcargo fix\fR is only capable of fixing code that is normally compiled with +\fBcargo check\fR\&. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed: +.sp +.RS 4 +.nf +cargo fix \-\-features foo +.fi +.RE +.sp +Similarly, other \fBcfg\fR expressions like platform\-specific code will need to +pass \fB\-\-target\fR to fix code for the given target. +.sp +.RS 4 +.nf +cargo fix \-\-target x86_64\-pc\-windows\-gnu +.fi +.RE +.sp +If you encounter any problems with \fBcargo fix\fR or otherwise have any questions +or feature requests please don\[cq]t hesitate to file an issue at +<https://github.com/rust\-lang/cargo>\&. +.SS "Edition migration" +The \fBcargo fix\fR subcommand can also be used to migrate a package from one +\fIedition\fR <https://doc.rust\-lang.org/edition\-guide/editions/transitioning\-an\-existing\-project\-to\-a\-new\-edition.html> to the next. The general procedure is: +.sp +.RS 4 +\h'-04' 1.\h'+01'Run \fBcargo fix \-\-edition\fR\&. Consider also using the \fB\-\-all\-features\fR flag if +your project has multiple features. You may also want to run \fBcargo fix \-\-edition\fR multiple times with different \fB\-\-target\fR flags if your project +has platform\-specific code gated by \fBcfg\fR attributes. +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Modify \fBCargo.toml\fR to set the \fIedition field\fR <https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-edition\-field> to the new edition. +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Run your project tests to verify that everything still works. If new +warnings are issued, you may want to consider running \fBcargo fix\fR again +(without the \fB\-\-edition\fR flag) to apply any suggestions given by the +compiler. +.RE +.sp +And hopefully that\[cq]s it! Just keep in mind of the caveats mentioned above that +\fBcargo fix\fR cannot update code for inactive features or \fBcfg\fR 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. +.SH "OPTIONS" +.SS "Fix options" +.sp +\fB\-\-broken\-code\fR +.RS 4 +Fix code even if it already has compiler errors. This is useful if \fBcargo fix\fR +fails to apply the changes. It will apply the changes and leave the broken +code in the working directory for you to inspect and manually fix. +.RE +.sp +\fB\-\-edition\fR +.RS 4 +Apply changes that will update the code to the next edition. This will not +update the edition in the \fBCargo.toml\fR manifest, which must be updated +manually after \fBcargo fix \-\-edition\fR has finished. +.RE +.sp +\fB\-\-edition\-idioms\fR +.RS 4 +Apply suggestions that will update code to the preferred style for the current +edition. +.RE +.sp +\fB\-\-allow\-no\-vcs\fR +.RS 4 +Fix code even if a VCS was not detected. +.RE +.sp +\fB\-\-allow\-dirty\fR +.RS 4 +Fix code even if the working directory has changes. +.RE +.sp +\fB\-\-allow\-staged\fR +.RS 4 +Fix code even if the working directory has staged changes. +.RE +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Fix only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Fix all members in the workspace. +.RE +.sp +\fB\-\-all\fR +.RS 4 +Deprecated alias for \fB\-\-workspace\fR\&. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo fix\fR will fix all targets +(\fB\-\-all\-targets\fR implied). Binaries are skipped if they have +\fBrequired\-features\fR that are missing. +.sp +Passing target selection flags will fix only the specified +targets. +.sp +Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also +support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. 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. +.sp +\fB\-\-lib\fR +.RS 4 +Fix the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Fix the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Fix all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Fix the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Fix all example targets. +.RE +.sp +\fB\-\-test\fR \fIname\fR\[u2026] +.RS 4 +Fix the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-tests\fR +.RS 4 +Fix all targets in test mode that have the \fBtest = true\fR manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the \fBtest\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-bench\fR \fIname\fR\[u2026] +.RS 4 +Fix the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-benches\fR +.RS 4 +Fix all targets in benchmark mode that have the \fBbench = true\fR +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the \fBbench\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-all\-targets\fR +.RS 4 +Fix all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Fix for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Fix optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Fix with the given profile. +.sp +As a special case, specifying the \fBtest\fR profile will also enable checking in +test mode which will enable checking tests and enable the \fBtest\fR cfg option. +See \fIrustc tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html> for more +detail. +.sp +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Fix the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Apply compiler suggestions to the local package: +.sp +.RS 4 +.nf +cargo fix +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Update a package to prepare it for the next edition: +.sp +.RS 4 +.nf +cargo fix \-\-edition +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Apply suggested idioms for the current edition: +.sp +.RS 4 +.nf +cargo fix \-\-edition\-idioms +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-check\fR(1) diff --git a/src/etc/man/cargo-generate-lockfile.1 b/src/etc/man/cargo-generate-lockfile.1 new file mode 100644 index 0000000..e9c9a93 --- /dev/null +++ b/src/etc/man/cargo-generate-lockfile.1 @@ -0,0 +1,157 @@ +'\" t +.TH "CARGO\-GENERATE\-LOCKFILE" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-generate\-lockfile \[em] Generate the lockfile for a package +.SH "SYNOPSIS" +\fBcargo generate\-lockfile\fR [\fIoptions\fR] +.SH "DESCRIPTION" +This command will create the \fBCargo.lock\fR lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt with the latest +available version of every package. +.sp +See also \fBcargo\-update\fR(1) which is also capable of creating a \fBCargo.lock\fR +lockfile and has more options for controlling update behavior. +.SH "OPTIONS" +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Create or update the lockfile for the current package or workspace: +.sp +.RS 4 +.nf +cargo generate\-lockfile +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-update\fR(1) diff --git a/src/etc/man/cargo-help.1 b/src/etc/man/cargo-help.1 new file mode 100644 index 0000000..6553285 --- /dev/null +++ b/src/etc/man/cargo-help.1 @@ -0,0 +1,34 @@ +'\" t +.TH "CARGO\-HELP" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-help \[em] Get help for a Cargo command +.SH "SYNOPSIS" +\fBcargo help\fR [\fIsubcommand\fR] +.SH "DESCRIPTION" +Prints a help message for the given command. +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Get help for a command: +.sp +.RS 4 +.nf +cargo help build +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Help is also available with the \fB\-\-help\fR flag: +.sp +.RS 4 +.nf +cargo build \-\-help +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-init.1 b/src/etc/man/cargo-init.1 new file mode 100644 index 0000000..1894f33 --- /dev/null +++ b/src/etc/man/cargo-init.1 @@ -0,0 +1,170 @@ +'\" t +.TH "CARGO\-INIT" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-init \[em] Create a new Cargo package in an existing directory +.SH "SYNOPSIS" +\fBcargo init\fR [\fIoptions\fR] [\fIpath\fR] +.SH "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. +.sp +If there are typically\-named Rust source files already in the directory, those +will be used. If not, then a sample \fBsrc/main.rs\fR file will be created, or +\fBsrc/lib.rs\fR if \fB\-\-lib\fR is passed. +.sp +If the directory is not already in a VCS repository, then a new repository +is created (see \fB\-\-vcs\fR below). +.sp +See \fBcargo\-new\fR(1) for a similar command which will create a new package in +a new directory. +.SH "OPTIONS" +.SS "Init Options" +.sp +\fB\-\-bin\fR +.RS 4 +Create a package with a binary target (\fBsrc/main.rs\fR). +This is the default behavior. +.RE +.sp +\fB\-\-lib\fR +.RS 4 +Create a package with a library target (\fBsrc/lib.rs\fR). +.RE +.sp +\fB\-\-edition\fR \fIedition\fR +.RS 4 +Specify the Rust edition to use. Default is 2021. +Possible values: 2015, 2018, 2021 +.RE +.sp +\fB\-\-name\fR \fIname\fR +.RS 4 +Set the package name. Defaults to the directory name. +.RE +.sp +\fB\-\-vcs\fR \fIvcs\fR +.RS 4 +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to \fBgit\fR or the configuration value +\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name +which will restrict publishing only to that registry. +.sp +Registry names are defined in \fICargo config files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +If not specified, the default registry defined by the \fBregistry.default\fR +config key is used. If the default registry is not set and \fB\-\-registry\fR is not +used, the \fBpublish\fR field will not be set which means that publishing will not +be restricted. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Create a binary Cargo package in the current directory: +.sp +.RS 4 +.nf +cargo init +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-new\fR(1) diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 new file mode 100644 index 0000000..4a5d28b --- /dev/null +++ b/src/etc/man/cargo-install.1 @@ -0,0 +1,508 @@ +'\" t +.TH "CARGO\-INSTALL" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-install \[em] Build and install a Rust binary +.SH "SYNOPSIS" +\fBcargo install\fR [\fIoptions\fR] \fIcrate\fR[@\fIversion\fR]\[u2026] +.br +\fBcargo install\fR [\fIoptions\fR] \fB\-\-path\fR \fIpath\fR +.br +\fBcargo install\fR [\fIoptions\fR] \fB\-\-git\fR \fIurl\fR [\fIcrate\fR\[u2026]] +.br +\fBcargo install\fR [\fIoptions\fR] \fB\-\-list\fR +.SH "DESCRIPTION" +This command manages Cargo\[cq]s local set of installed binary crates. Only +packages which have executable \fB[[bin]]\fR or \fB[[example]]\fR targets can be +installed, and all executables are installed into the installation root\[cq]s +\fBbin\fR folder. +.sp +The installation root is determined, in order of precedence: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB\-\-root\fR option +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR environment variable +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html> +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR environment variable +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR +.RE +.sp +There are multiple sources from which a crate can be installed. The default +location is crates.io but the \fB\-\-git\fR, \fB\-\-path\fR, and \fB\-\-registry\fR flags can +change this source. If the source contains more than one package (such as +crates.io or a git repository with multiple crates) the \fIcrate\fR argument is +required to indicate which crate should be installed. +.sp +Crates from crates.io can optionally specify the version they wish to install +via the \fB\-\-version\fR flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the \fB\-\-bin\fR argument can selectively install only +one of them, and if you\[cq]d rather install examples the \fB\-\-example\fR argument can +be used as well. +.sp +If the package is already installed, Cargo will reinstall it if the installed +version does not appear to be up\-to\-date. If any of the following values +change, then Cargo will reinstall the package: +.sp +.RS 4 +\h'-04'\(bu\h'+02'The package version and source. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'The set of binary names installed. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'The chosen features. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'The profile (\fB\-\-profile\fR). +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'The target (\fB\-\-target\fR). +.RE +.sp +Installing with \fB\-\-path\fR will always build and install, unless there are +conflicting binaries from another package. The \fB\-\-force\fR flag may be used to +force Cargo to always reinstall the package. +.sp +If the source is crates.io or \fB\-\-git\fR then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the \fBCARGO_TARGET_DIR\fR environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems. +.SS "Dealing with the Lockfile" +By default, the \fBCargo.lock\fR file that is included with the package will be +ignored. This means that Cargo will recompute which versions of dependencies +to use, possibly using newer versions that have been released since the +package was published. The \fB\-\-locked\fR flag can be used to force Cargo to use +the packaged \fBCargo.lock\fR file if it is available. This may be useful for +ensuring reproducible builds, to use the exact same set of dependencies that +were available when the package was published. It may also be useful if a +newer version of a dependency is published that no longer builds on your +system, or has other problems. The downside to using \fB\-\-locked\fR is that you +will not receive any fixes or updates to any dependency. Note that Cargo did +not start publishing \fBCargo.lock\fR files until version 1.37, which means +packages published with prior versions will not have a \fBCargo.lock\fR file +available. +.SS "Configuration Discovery" +This command operates on system or user level, not project level. +This means that the local \fIconfiguration discovery\fR <https://doc.rust\-lang.org/cargo/reference/config.html#hierarchical\-structure> is ignored. +Instead, the configuration discovery begins at \fB$CARGO_HOME/config.toml\fR\&. +If the package is installed with \fB\-\-path $PATH\fR, the local configuration +will be used, beginning discovery at \fB$PATH/.cargo/config.toml\fR\&. +.SH "OPTIONS" +.SS "Install Options" +.sp +\fB\-\-vers\fR \fIversion\fR, +\fB\-\-version\fR \fIversion\fR +.RS 4 +Specify a version to install. This may be a \fIversion +requirement\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.md>, like \fB~1.2\fR, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as \fB^\fR or \fB~\fR), then it must be in the form +\fIMAJOR.MINOR.PATCH\fR, and will install exactly that version; it is \fInot\fR +treated as a caret requirement like Cargo dependencies are. +.RE +.sp +\fB\-\-git\fR \fIurl\fR +.RS 4 +Git URL to install the specified crate from. +.RE +.sp +\fB\-\-branch\fR \fIbranch\fR +.RS 4 +Branch to use when installing from git. +.RE +.sp +\fB\-\-tag\fR \fItag\fR +.RS 4 +Tag to use when installing from git. +.RE +.sp +\fB\-\-rev\fR \fIsha\fR +.RS 4 +Specific commit to use when installing from git. +.RE +.sp +\fB\-\-path\fR \fIpath\fR +.RS 4 +Filesystem path to local crate to install. +.RE +.sp +\fB\-\-list\fR +.RS 4 +List all installed packages and their versions. +.RE +.sp +\fB\-f\fR, +\fB\-\-force\fR +.RS 4 +Force overwriting existing crates or binaries. This can be used if a package +has installed a binary with the same name as another package. This is also +useful if something has changed on the system that you want to rebuild with, +such as a newer version of \fBrustc\fR\&. +.RE +.sp +\fB\-\-no\-track\fR +.RS 4 +By default, Cargo keeps track of the installed packages with a metadata file +stored in the installation root directory. This flag tells Cargo not to use or +create that file. With this flag, Cargo will refuse to overwrite any existing +files unless the \fB\-\-force\fR flag is used. This also disables Cargo\[cq]s ability to +protect against multiple concurrent invocations of Cargo installing at the +same time. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Install only the specified binary. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Install all binaries. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Install only the specified example. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Install all examples. +.RE +.sp +\fB\-\-root\fR \fIdir\fR +.RS 4 +Directory to install packages into. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to use. Registry names are defined in \fICargo config +files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. +.RE +.sp +\fB\-\-index\fR \fIindex\fR +.RS 4 +The URL of the registry index to use. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Install for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to a new temporary folder located in the +temporary directory of the platform. +.sp +When using \fB\-\-path\fR, by default it will use \fBtarget\fR directory in the workspace +of the local crate unless \fB\-\-target\-dir\fR +is specified. +.RE +.sp +\fB\-\-debug\fR +.RS 4 +Build with the \fBdev\fR profile instead the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Install with the given profile. +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Install or upgrade a package from crates.io: +.sp +.RS 4 +.nf +cargo install ripgrep +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Install or reinstall the package in the current directory: +.sp +.RS 4 +.nf +cargo install \-\-path . +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'View the list of installed packages: +.sp +.RS 4 +.nf +cargo install \-\-list +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-uninstall\fR(1), \fBcargo\-search\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-locate-project.1 b/src/etc/man/cargo-locate-project.1 new file mode 100644 index 0000000..4585ec0 --- /dev/null +++ b/src/etc/man/cargo-locate-project.1 @@ -0,0 +1,149 @@ +'\" t +.TH "CARGO\-LOCATE\-PROJECT" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-locate\-project \[em] Print a JSON representation of a Cargo.toml file\[cq]s location +.SH "SYNOPSIS" +\fBcargo locate\-project\fR [\fIoptions\fR] +.SH "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 \fBCargo.toml\fR starting from the current +working directory. +.sp +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 \fB\-\-workspace\fR flag. The root +workspace is found by traversing further upward or by using the field \fBpackage.workspace\fR after +locating the manifest of a workspace member. +.SH "OPTIONS" +.sp +\fB\-\-workspace\fR +.RS 4 +Locate the \fBCargo.toml\fR at the root of the workspace, as opposed to the current +workspace member. +.RE +.SS "Display Options" +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The representation in which to print the project location. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (default): JSON object with the path under the key \[lq]root\[rq]\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBplain\fR: Just the path. +.RE +.RE +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Display the path to the manifest based on the current directory: +.sp +.RS 4 +.nf +cargo locate\-project +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-login.1 b/src/etc/man/cargo-login.1 new file mode 100644 index 0000000..8d8137b --- /dev/null +++ b/src/etc/man/cargo-login.1 @@ -0,0 +1,134 @@ +'\" t +.TH "CARGO\-LOGIN" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-login \[em] Save an API token from the registry locally +.SH "SYNOPSIS" +\fBcargo login\fR [\fIoptions\fR] [\fItoken\fR] +.SH "DESCRIPTION" +This command will save the API token to disk so that commands that require +authentication, such as \fBcargo\-publish\fR(1), will be automatically +authenticated. The token is saved in \fB$CARGO_HOME/credentials.toml\fR\&. \fBCARGO_HOME\fR +defaults to \fB\&.cargo\fR in your home directory. +.sp +If the \fItoken\fR argument is not specified, it will be read from stdin. +.sp +The API token for crates.io may be retrieved from <https://crates.io/me>\&. +.sp +Take care to keep the token secret, it should not be shared with anyone else. +.SH "OPTIONS" +.SS "Login Options" +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to use. Registry names are defined in \fICargo config +files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Save the API token to disk: +.sp +.RS 4 +.nf +cargo login +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 new file mode 100644 index 0000000..d4aafa8 --- /dev/null +++ b/src/etc/man/cargo-metadata.1 @@ -0,0 +1,482 @@ +'\" t +.TH "CARGO\-METADATA" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-metadata \[em] Machine\-readable metadata about the current package +.SH "SYNOPSIS" +\fBcargo metadata\fR [\fIoptions\fR] +.SH "DESCRIPTION" +Output JSON to stdout containing information about the workspace members and +resolved dependencies of the current package. +.sp +It is recommended to include the \fB\-\-format\-version\fR flag to future\-proof +your code to ensure the output is in the format you are expecting. +.sp +See the \fIcargo_metadata crate\fR <https://crates.io/crates/cargo_metadata> +for a Rust API for reading the metadata. +.SH "OUTPUT FORMAT" +The output has the following format: +.sp +.RS 4 +.nf +{ + /* 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 + } + } + } +} +.fi +.RE +.SH "OPTIONS" +.SS "Output Options" +.sp +\fB\-\-no\-deps\fR +.RS 4 +Output information only about the workspace members and don\[cq]t fetch +dependencies. +.RE +.sp +\fB\-\-format\-version\fR \fIversion\fR +.RS 4 +Specify the version of the output format to use. Currently \fB1\fR is the only +possible value. +.RE +.sp +\fB\-\-filter\-platform\fR \fItriple\fR +.RS 4 +This filters the \fBresolve\fR output to only include dependencies for the +given \fItarget triple\fR <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&. +Without this flag, the resolve includes all targets. +.sp +Note that the dependencies listed in the \[lq]packages\[rq] array still includes all +dependencies. Each package definition is intended to be an unaltered +reproduction of the information within \fBCargo.toml\fR\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Output JSON about the current package: +.sp +.RS 4 +.nf +cargo metadata \-\-format\-version=1 +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-new.1 b/src/etc/man/cargo-new.1 new file mode 100644 index 0000000..86f07c4 --- /dev/null +++ b/src/etc/man/cargo-new.1 @@ -0,0 +1,165 @@ +'\" t +.TH "CARGO\-NEW" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-new \[em] Create a new Cargo package +.SH "SYNOPSIS" +\fBcargo new\fR [\fIoptions\fR] \fIpath\fR +.SH "DESCRIPTION" +This command will create a new Cargo package in the given directory. This +includes a simple template with a \fBCargo.toml\fR manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see \fB\-\-vcs\fR below). +.sp +See \fBcargo\-init\fR(1) for a similar command which will create a new manifest +in an existing directory. +.SH "OPTIONS" +.SS "New Options" +.sp +\fB\-\-bin\fR +.RS 4 +Create a package with a binary target (\fBsrc/main.rs\fR). +This is the default behavior. +.RE +.sp +\fB\-\-lib\fR +.RS 4 +Create a package with a library target (\fBsrc/lib.rs\fR). +.RE +.sp +\fB\-\-edition\fR \fIedition\fR +.RS 4 +Specify the Rust edition to use. Default is 2021. +Possible values: 2015, 2018, 2021 +.RE +.sp +\fB\-\-name\fR \fIname\fR +.RS 4 +Set the package name. Defaults to the directory name. +.RE +.sp +\fB\-\-vcs\fR \fIvcs\fR +.RS 4 +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to \fBgit\fR or the configuration value +\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name +which will restrict publishing only to that registry. +.sp +Registry names are defined in \fICargo config files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +If not specified, the default registry defined by the \fBregistry.default\fR +config key is used. If the default registry is not set and \fB\-\-registry\fR is not +used, the \fBpublish\fR field will not be set which means that publishing will not +be restricted. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Create a binary Cargo package in the given directory: +.sp +.RS 4 +.nf +cargo new foo +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-init\fR(1) diff --git a/src/etc/man/cargo-owner.1 b/src/etc/man/cargo-owner.1 new file mode 100644 index 0000000..1516af5 --- /dev/null +++ b/src/etc/man/cargo-owner.1 @@ -0,0 +1,196 @@ +'\" t +.TH "CARGO\-OWNER" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-owner \[em] Manage the owners of a crate on the registry +.SH "SYNOPSIS" +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-add\fR \fIlogin\fR [\fIcrate\fR] +.br +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-remove\fR \fIlogin\fR [\fIcrate\fR] +.br +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-list\fR [\fIcrate\fR] +.SH "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! +.sp +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). +.sp +If the crate name is not specified, it will use the package name from the +current directory. +.sp +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/publishing.html#cargo\-owner> for more +information about owners and publishing. +.SH "OPTIONS" +.SS "Owner Options" +.sp +\fB\-a\fR, +\fB\-\-add\fR \fIlogin\fR\[u2026] +.RS 4 +Invite the given user or team as an owner. +.RE +.sp +\fB\-r\fR, +\fB\-\-remove\fR \fIlogin\fR\[u2026] +.RS 4 +Remove the given user or team as an owner. +.RE +.sp +\fB\-l\fR, +\fB\-\-list\fR +.RS 4 +List owners of a crate. +.RE +.sp +\fB\-\-token\fR \fItoken\fR +.RS 4 +API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by \fBcargo\-login\fR(1)). +.sp +\fICargo config\fR <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 \fBCARGO_REGISTRY_TOKEN\fR environment +variable. Tokens for other registries may be specified with environment +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name +of the registry in all capital letters. +.RE +.sp +\fB\-\-index\fR \fIindex\fR +.RS 4 +The URL of the registry index to use. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to use. Registry names are defined in \fICargo config +files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'List owners of a package: +.sp +.RS 4 +.nf +cargo owner \-\-list foo +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Invite an owner to a package: +.sp +.RS 4 +.nf +cargo owner \-\-add username foo +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Remove an owner from a package: +.sp +.RS 4 +.nf +cargo owner \-\-remove username foo +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 new file mode 100644 index 0000000..ba572b1 --- /dev/null +++ b/src/etc/man/cargo-package.1 @@ -0,0 +1,350 @@ +'\" t +.TH "CARGO\-PACKAGE" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-package \[em] Assemble the local package into a distributable tarball +.SH "SYNOPSIS" +\fBcargo package\fR [\fIoptions\fR] +.SH "DESCRIPTION" +This command will create a distributable, compressed \fB\&.crate\fR file with the +source code of the package in the current directory. The resulting file will +be stored in the \fBtarget/package\fR directory. This performs the following +steps: +.sp +.RS 4 +\h'-04' 1.\h'+01'Load and check the current workspace, performing some basic checks. +.sp +.RS 4 +\h'-04'\(bu\h'+02'Path dependencies are not allowed unless they have a version key. Cargo +will ignore the path key for dependencies in published packages. +\fBdev\-dependencies\fR do not have this restriction. +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Create the compressed \fB\&.crate\fR file. +.sp +.RS 4 +\h'-04'\(bu\h'+02'The original \fBCargo.toml\fR file is rewritten and normalized. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB[patch]\fR, \fB[replace]\fR, and \fB[workspace]\fR sections are removed from the +manifest. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBCargo.lock\fR is automatically included if the package contains an +executable binary or example target. \fBcargo\-install\fR(1) will use the +packaged lock file if the \fB\-\-locked\fR flag is used. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'A \fB\&.cargo_vcs_info.json\fR file is included that contains information +about the current VCS checkout hash if available (not included with +\fB\-\-allow\-dirty\fR). +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Extract the \fB\&.crate\fR file and build it to verify it can build. +.sp +.RS 4 +\h'-04'\(bu\h'+02'This will rebuild your package from scratch to ensure that it can be +built from a pristine state. The \fB\-\-no\-verify\fR flag can be used to skip +this step. +.RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Check that build scripts did not modify any source files. +.RE +.sp +The list of files included can be controlled with the \fBinclude\fR and \fBexclude\fR +fields in the manifest. +.sp +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/publishing.html> for more details about +packaging and publishing. +.SS ".cargo_vcs_info.json format" +Will generate a \fB\&.cargo_vcs_info.json\fR in the following format +.sp +.RS 4 +.nf +{ + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" +} +.fi +.RE +.sp +\fBpath_in_vcs\fR will be set to a repo\-relative path for packages +in subdirectories of the version control repository. +.SH "OPTIONS" +.SS "Package Options" +.sp +\fB\-l\fR, +\fB\-\-list\fR +.RS 4 +Print files included in a package without making one. +.RE +.sp +\fB\-\-no\-verify\fR +.RS 4 +Don\[cq]t verify the contents by building them. +.RE +.sp +\fB\-\-no\-metadata\fR +.RS 4 +Ignore warnings about a lack of human\-usable metadata (such as the description +or the license). +.RE +.sp +\fB\-\-allow\-dirty\fR +.RS 4 +Allow working directories with uncommitted VCS changes to be packaged. +.RE +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Package only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Package all members in the workspace. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Package for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Create a compressed \fB\&.crate\fR file of the current package: +.sp +.RS 4 +.nf +cargo package +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-pkgid.1 b/src/etc/man/cargo-pkgid.1 new file mode 100644 index 0000000..6f07851 --- /dev/null +++ b/src/etc/man/cargo-pkgid.1 @@ -0,0 +1,242 @@ +'\" t +.TH "CARGO\-PKGID" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-pkgid \[em] Print a fully qualified package specification +.SH "SYNOPSIS" +\fBcargo pkgid\fR [\fIoptions\fR] [\fIspec\fR] +.SH "DESCRIPTION" +Given a \fIspec\fR argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if \fIspec\fR is ambiguous as to which package it refers to in +the dependency graph. If no \fIspec\fR is given, then the specifier for the local +package is printed. +.sp +This command requires that a lockfile is available and dependencies have been +fetched. +.sp +A package specifier consists of a name, version, and source URL. You are +allowed to use partial specifiers to succinctly match a specific package as +long as it matches only one package. The format of a \fIspec\fR can be one of the +following: + +.TS +allbox tab(:); +lt lt. +T{ +SPEC Structure +T}:T{ +Example SPEC +T} +T{ +\fIname\fR +T}:T{ +\fBbitflags\fR +T} +T{ +\fIname\fR\fB@\fR\fIversion\fR +T}:T{ +\fBbitflags@1.0.4\fR +T} +T{ +\fIurl\fR +T}:T{ +\fBhttps://github.com/rust\-lang/cargo\fR +T} +T{ +\fIurl\fR\fB#\fR\fIversion\fR +T}:T{ +\fBhttps://github.com/rust\-lang/cargo#0.33.0\fR +T} +T{ +\fIurl\fR\fB#\fR\fIname\fR +T}:T{ +\fBhttps://github.com/rust\-lang/crates.io\-index#bitflags\fR +T} +T{ +\fIurl\fR\fB#\fR\fIname\fR\fB:\fR\fIversion\fR +T}:T{ +\fBhttps://github.com/rust\-lang/cargo#crates\-io@0.21.0\fR +T} +.TE +.sp +.SH "OPTIONS" +.SS "Package Selection" +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +Get the package ID for the given package instead of the current package. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Retrieve package specification for \fBfoo\fR package: +.sp +.RS 4 +.nf +cargo pkgid foo +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Retrieve package specification for version 1.0.0 of \fBfoo\fR: +.sp +.RS 4 +.nf +cargo pkgid foo@1.0.0 +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Retrieve package specification for \fBfoo\fR from crates.io: +.sp +.RS 4 +.nf +cargo pkgid https://github.com/rust\-lang/crates.io\-index#foo +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Retrieve package specification for \fBfoo\fR from a local package: +.sp +.RS 4 +.nf +cargo pkgid file:///path/to/local/package#foo +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 new file mode 100644 index 0000000..3ce140d --- /dev/null +++ b/src/etc/man/cargo-publish.1 @@ -0,0 +1,300 @@ +'\" t +.TH "CARGO\-PUBLISH" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-publish \[em] Upload a package to the registry +.SH "SYNOPSIS" +\fBcargo publish\fR [\fIoptions\fR] +.SH "DESCRIPTION" +This command will create a distributable, compressed \fB\&.crate\fR file with the +source code of the package in the current directory and upload it to a +registry. The default registry is <https://crates.io>\&. This performs the +following steps: +.sp +.RS 4 +\h'-04' 1.\h'+01'Performs a few checks, including: +.sp +.RS 4 +\h'-04'\(bu\h'+02'Checks the \fBpackage.publish\fR key in the manifest for restrictions on +which registries you are allowed to publish to. +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Create a \fB\&.crate\fR file by following the steps in \fBcargo\-package\fR(1). +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Upload the crate to the registry. Note that the server will perform +additional checks on the crate. +.RE +.sp +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). +.sp +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/publishing.html> for more details about +packaging and publishing. +.SH "OPTIONS" +.SS "Publish Options" +.sp +\fB\-\-dry\-run\fR +.RS 4 +Perform all checks without uploading. +.RE +.sp +\fB\-\-token\fR \fItoken\fR +.RS 4 +API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by \fBcargo\-login\fR(1)). +.sp +\fICargo config\fR <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 \fBCARGO_REGISTRY_TOKEN\fR environment +variable. Tokens for other registries may be specified with environment +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name +of the registry in all capital letters. +.RE +.sp +\fB\-\-no\-verify\fR +.RS 4 +Don\[cq]t verify the contents by building them. +.RE +.sp +\fB\-\-allow\-dirty\fR +.RS 4 +Allow working directories with uncommitted VCS changes to be packaged. +.RE +.sp +\fB\-\-index\fR \fIindex\fR +.RS 4 +The URL of the registry index to use. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to publish to. Registry names are defined in \fICargo +config files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, and there is a +\fI\f(BIpackage.publish\fI\fR <https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-publish\-field> field in +\fBCargo.toml\fR with a single registry, then it will publish to that registry. +Otherwise it will use the default registry, which is defined by the +\fI\f(BIregistry.default\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#registrydefault> config key +which defaults to \fBcrates\-io\fR\&. +.RE +.SS "Package Selection" +By default, the package in the current working directory is selected. The \fB\-p\fR +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +The package to publish. See \fBcargo\-pkgid\fR(1) for the SPEC +format. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Publish for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Publish the current package: +.sp +.RS 4 +.nf +cargo publish +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-package\fR(1), \fBcargo\-login\fR(1) diff --git a/src/etc/man/cargo-remove.1 b/src/etc/man/cargo-remove.1 new file mode 100644 index 0000000..476a1cc --- /dev/null +++ b/src/etc/man/cargo-remove.1 @@ -0,0 +1,201 @@ +'\" t +.TH "CARGO\-REMOVE" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-remove \[em] Remove dependencies from a Cargo.toml manifest file +.SH "SYNOPSIS" +\fBcargo remove\fR [\fIoptions\fR] \fIdependency\fR\[u2026] +.SH "DESCRIPTION" +Remove one or more dependencies from a \fBCargo.toml\fR manifest. +.SH "OPTIONS" +.SS "Section options" +.sp +\fB\-\-dev\fR +.RS 4 +Remove as a \fIdevelopment dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#development\-dependencies>\&. +.RE +.sp +\fB\-\-build\fR +.RS 4 +Remove as a \fIbuild dependency\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#build\-dependencies>\&. +.RE +.sp +\fB\-\-target\fR \fItarget\fR +.RS 4 +Remove as a dependency to the \fIgiven target platform\fR <https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.html#platform\-specific\-dependencies>\&. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-\-dry\-run\fR +.RS 4 +Don\[cq]t actually write to the manifest. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Package Selection" +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Package to remove from. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Remove \fBregex\fR as a dependency +.sp +.RS 4 +.nf +cargo remove regex +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Remove \fBtrybuild\fR as a dev\-dependency +.sp +.RS 4 +.nf +cargo remove \-\-dev trybuild +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Remove \fBnom\fR from the \fBx86_64\-pc\-windows\-gnu\fR dependencies table +.sp +.RS 4 +.nf +cargo remove \-\-target x86_64\-pc\-windows\-gnu nom +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-add\fR(1) diff --git a/src/etc/man/cargo-report.1 b/src/etc/man/cargo-report.1 new file mode 100644 index 0000000..24b6305 --- /dev/null +++ b/src/etc/man/cargo-report.1 @@ -0,0 +1,48 @@ +'\" t +.TH "CARGO\-REPORT" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-report \[em] Generate and display various kinds of reports +.SH "SYNOPSIS" +\fBcargo report\fR \fItype\fR [\fIoptions\fR] +.SS "DESCRIPTION" +Displays a report of the given \fItype\fR \[em] currently, only \fBfuture\-incompat\fR is supported +.SH "OPTIONS" +.sp +\fB\-\-id\fR \fIid\fR +.RS 4 +Show the report with the specified Cargo\-generated id +.RE +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Only display a report for the specified package +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Display the latest future\-incompat report: +.sp +.RS 4 +.nf +cargo report future\-incompat +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Display the latest future\-incompat report for a specific package: +.sp +.RS 4 +.nf +cargo report future\-incompat \-\-package my\-dep:0.0.1 +.fi +.RE +.RE +.SH "SEE ALSO" +\fIFuture incompat report\fR <https://doc.rust\-lang.org/cargo/reference/future\-incompat\-report.html> +.sp +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 new file mode 100644 index 0000000..efcb819 --- /dev/null +++ b/src/etc/man/cargo-run.1 @@ -0,0 +1,339 @@ +'\" t +.TH "CARGO\-RUN" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-run \[em] Run the current package +.SH "SYNOPSIS" +\fBcargo run\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] +.SH "DESCRIPTION" +Run a binary or example of the local package. +.sp +All the arguments following the two dashes (\fB\-\-\fR) are passed to the binary to +run. If you\[cq]re passing arguments to both Cargo and the binary, the ones after +\fB\-\-\fR go to the binary, the ones before go to Cargo. +.SH "OPTIONS" +.SS "Package Selection" +By default, the package in the current working directory is selected. The \fB\-p\fR +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +The package to run. See \fBcargo\-pkgid\fR(1) for the SPEC +format. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo run\fR will run the binary +target. If there are multiple binary targets, you must pass a target flag to +choose one. Or, the \fBdefault\-run\fR field may be specified in the \fB[package]\fR +section of \fBCargo.toml\fR to choose the name of the binary to run by default. +.sp +\fB\-\-bin\fR \fIname\fR +.RS 4 +Run the specified binary. +.RE +.sp +\fB\-\-example\fR \fIname\fR +.RS 4 +Run the specified example. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Run for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Run optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Run with the given profile. +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Run the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Build the local package and run its main target (assuming only one binary): +.sp +.RS 4 +.nf +cargo run +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Run an example with extra arguments: +.sp +.RS 4 +.nf +cargo run \-\-example exname \-\- \-\-exoption exarg1 exarg2 +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 new file mode 100644 index 0000000..7a5789d --- /dev/null +++ b/src/etc/man/cargo-rustc.1 @@ -0,0 +1,476 @@ +'\" t +.TH "CARGO\-RUSTC" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-rustc \[em] Compile the current package, and pass extra options to the compiler +.SH "SYNOPSIS" +\fBcargo rustc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] +.SH "DESCRIPTION" +The specified target for the current package (or package specified by \fB\-p\fR if +provided) will be compiled along with all of its dependencies. The specified +\fIargs\fR will all be passed to the final compiler invocation, not any of the +dependencies. Note that the compiler will still unconditionally receive +arguments such as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified +\fIargs\fR will simply be added to the compiler invocation. +.sp +See <https://doc.rust\-lang.org/rustc/index.html> for documentation on rustc +flags. +.sp +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which +target is compiled. +.sp +To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fR +\fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> or the +\fBbuild.rustflags\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.SH "OPTIONS" +.SS "Package Selection" +By default, the package in the current working directory is selected. The \fB\-p\fR +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +The package to build. See \fBcargo\-pkgid\fR(1) for the SPEC +format. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo rustc\fR will build all +binary and library targets of the selected package. +.sp +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 \fBCARGO_BIN_EXE_<name>\fR +\fIenvironment variable\fR <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 +\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the +executable. +.sp +Passing target selection flags will build only the specified +targets. +.sp +Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also +support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. 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. +.sp +\fB\-\-lib\fR +.RS 4 +Build the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Build the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Build all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Build the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Build all example targets. +.RE +.sp +\fB\-\-test\fR \fIname\fR\[u2026] +.RS 4 +Build the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-tests\fR +.RS 4 +Build all targets in test mode that have the \fBtest = true\fR manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the \fBtest\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-bench\fR \fIname\fR\[u2026] +.RS 4 +Build the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-benches\fR +.RS 4 +Build all targets in benchmark mode that have the \fBbench = true\fR +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the \fBbench\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-all\-targets\fR +.RS 4 +Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Build for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Build optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Build with the given profile. +.sp +The \fBrustc\fR subcommand will treat the following named profiles with special behaviors: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBcheck\fR \[em] Builds in the same way as the \fBcargo\-check\fR(1) command with +the \fBdev\fR profile. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBtest\fR \[em] Builds in the same way as the \fBcargo\-test\fR(1) command, +enabling building in test mode which will enable tests and enable the \fBtest\fR +cfg option. See \fIrustc +tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html> for more detail. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBbench\fR \[em] Builds in the same was as the \fBcargo\-bench\fR(1) command, +similar to the \fBtest\fR profile. +.RE +.sp +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Build the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.sp +\fB\-\-crate\-type\fR \fIcrate\-type\fR +.RS 4 +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 \fBcrate\-type\fR +field in the manifest for configurating a Cargo target. See +\fI\f(BIcrate\-type\fI field\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#the\-crate\-type\-field> +for possible values. +.sp +If the manifest contains a list, and \fB\-\-crate\-type\fR is provided, +the command\-line argument value will override what is in the manifest. +.sp +This flag only works when building a \fBlib\fR or \fBexample\fR library target. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.sp +\fB\-\-future\-incompat\-report\fR +.RS 4 +Displays a future\-incompat report for any future\-incompatible warnings +produced during execution of this command +.sp +See \fBcargo\-report\fR(1) +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Check if your package (not including dependencies) uses unsafe code: +.sp +.RS 4 +.nf +cargo rustc \-\-lib \-\- \-D unsafe\-code +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Try an experimental flag on the nightly compiler, such as this which prints +the size of every type: +.sp +.RS 4 +.nf +cargo rustc \-\-lib \-\- \-Z print\-type\-sizes +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Override \fBcrate\-type\fR field in Cargo.toml with command\-line option: +.sp +.RS 4 +.nf +cargo rustc \-\-lib \-\-crate\-type lib,cdylib +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-build\fR(1), \fBrustc\fR(1) diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 new file mode 100644 index 0000000..6956153 --- /dev/null +++ b/src/etc/man/cargo-rustdoc.1 @@ -0,0 +1,415 @@ +'\" t +.TH "CARGO\-RUSTDOC" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-rustdoc \[em] Build a package\[cq]s documentation, using specified custom flags +.SH "SYNOPSIS" +\fBcargo rustdoc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] +.SH "DESCRIPTION" +The specified target for the current package (or package specified by \fB\-p\fR if +provided) will be documented with the specified \fIargs\fR being passed to the +final rustdoc invocation. Dependencies will not be documented as part of this +command. Note that rustdoc will still unconditionally receive arguments such +as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified \fIargs\fR will simply +be added to the rustdoc invocation. +.sp +See <https://doc.rust\-lang.org/rustdoc/index.html> for documentation on rustdoc +flags. +.sp +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which +target is compiled. +.sp +To pass flags to all rustdoc processes spawned by Cargo, use the +\fBRUSTDOCFLAGS\fR \fIenvironment variable\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> +or the \fBbuild.rustdocflags\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.SH "OPTIONS" +.SS "Documentation Options" +.sp +\fB\-\-open\fR +.RS 4 +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the \fBBROWSER\fR environment variable +or use the \fI\f(BIdoc.browser\fI\fR <https://doc.rust\-lang.org/cargo/reference/config.html#docbrowser> configuration +option. +.RE +.SS "Package Selection" +By default, the package in the current working directory is selected. The \fB\-p\fR +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +The package to document. See \fBcargo\-pkgid\fR(1) for the SPEC +format. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo rustdoc\fR will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +\fBrequired\-features\fR that are missing. +.sp +Passing target selection flags will document only the specified +targets. +.sp +Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also +support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. 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. +.sp +\fB\-\-lib\fR +.RS 4 +Document the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Document the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Document all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Document the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Document all example targets. +.RE +.sp +\fB\-\-test\fR \fIname\fR\[u2026] +.RS 4 +Document the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-tests\fR +.RS 4 +Document all targets in test mode that have the \fBtest = true\fR manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the \fBtest\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-bench\fR \fIname\fR\[u2026] +.RS 4 +Document the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-benches\fR +.RS 4 +Document all targets in benchmark mode that have the \fBbench = true\fR +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the \fBbench\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-all\-targets\fR +.RS 4 +Document all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Document for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Document optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Document with the given profile. +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Document the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Build documentation with custom CSS included from a given file: +.sp +.RS 4 +.nf +cargo rustdoc \-\-lib \-\- \-\-extend\-css extra.css +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-doc\fR(1), \fBrustdoc\fR(1) diff --git a/src/etc/man/cargo-search.1 b/src/etc/man/cargo-search.1 new file mode 100644 index 0000000..8704b66 --- /dev/null +++ b/src/etc/man/cargo-search.1 @@ -0,0 +1,137 @@ +'\" t +.TH "CARGO\-SEARCH" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-search \[em] Search packages in crates.io +.SH "SYNOPSIS" +\fBcargo search\fR [\fIoptions\fR] [\fIquery\fR\[u2026]] +.SH "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 \fBCargo.toml\fR manifest. +.SH "OPTIONS" +.SS "Search Options" +.sp +\fB\-\-limit\fR \fIlimit\fR +.RS 4 +Limit the number of results (default: 10, max: 100). +.RE +.sp +\fB\-\-index\fR \fIindex\fR +.RS 4 +The URL of the registry index to use. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to use. Registry names are defined in \fICargo config +files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Search for a package from crates.io: +.sp +.RS 4 +.nf +cargo search serde +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-install\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 new file mode 100644 index 0000000..dc999f1 --- /dev/null +++ b/src/etc/man/cargo-test.1 @@ -0,0 +1,574 @@ +'\" t +.TH "CARGO\-TEST" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-test \[em] Execute unit and integration tests of a package +.SH "SYNOPSIS" +\fBcargo test\fR [\fIoptions\fR] [\fItestname\fR] [\fB\-\-\fR \fItest\-options\fR] +.SH "DESCRIPTION" +Compile and execute unit, integration, and documentation tests. +.sp +The test filtering argument \fBTESTNAME\fR and all the arguments following the two +dashes (\fB\-\-\fR) are passed to the test binaries and thus to \fIlibtest\fR (rustc\[cq]s +built in unit\-test and micro\-benchmarking framework). If you\[cq]re passing +arguments to both Cargo and the binary, the ones after \fB\-\-\fR go to the binary, +the ones before go to Cargo. For details about libtest\[cq]s arguments see the +output of \fBcargo test \-\- \-\-help\fR and check out the rustc book\[cq]s chapter on +how tests work at <https://doc.rust\-lang.org/rustc/tests/index.html>\&. +.sp +As an example, this will filter for tests with \fBfoo\fR in their name and run them +on 3 threads in parallel: +.sp +.RS 4 +.nf +cargo test foo \-\- \-\-test\-threads 3 +.fi +.RE +.sp +Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates a special +executable by linking your code with libtest. The executable automatically +runs all functions annotated with the \fB#[test]\fR attribute in multiple threads. +\fB#[bench]\fR annotated functions will also be run with one iteration to verify +that they are functional. +.sp +If the package contains multiple test targets, each target compiles to a +special executable as aforementioned, and then is run serially. +.sp +The libtest harness may be disabled by setting \fBharness = false\fR in the target +manifest settings, in which case your code will need to provide its own \fBmain\fR +function to handle running tests. +.SS "Documentation tests" +Documentation tests are also run by default, which is handled by \fBrustdoc\fR\&. It +extracts code samples from documentation comments of the library target, and +then executes them. +.sp +Different from normal test targets, each code block compiles to a doctest +executable on the fly with \fBrustc\fR\&. 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 \fB\-\-jobs\fR 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. +.sp +See the \fIrustdoc book\fR <https://doc.rust\-lang.org/rustdoc/> for more information +on writing doc tests. +.SH "OPTIONS" +.SS "Test Options" +.sp +\fB\-\-no\-run\fR +.RS 4 +Compile, but don\[cq]t run tests. +.RE +.sp +\fB\-\-no\-fail\-fast\fR +.RS 4 +Run all tests regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all tests +within the executable to completion, this flag only applies to the executable +as a whole. +.RE +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Test only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Test all members in the workspace. +.RE +.sp +\fB\-\-all\fR +.RS 4 +Deprecated alias for \fB\-\-workspace\fR\&. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Target Selection" +When no target selection options are given, \fBcargo test\fR will build the +following targets of the selected packages: +.sp +.RS 4 +\h'-04'\(bu\h'+02'lib \[em] used to link with binaries, examples, integration tests, and doc tests +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'bins (only if integration tests are built and required features are +available) +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'examples \[em] to ensure they compile +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'lib as a unit test +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'bins as unit tests +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'integration tests +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'doc tests for the lib target +.RE +.sp +The default behavior can be changed by setting the \fBtest\fR flag for the target +in the manifest settings. Setting examples to \fBtest = true\fR will build and run +the example as a test. Setting targets to \fBtest = false\fR will stop them from +being tested by default. Target selection options that take a target by name +ignore the \fBtest\fR flag and will always test the given target. +.sp +Doc tests for libraries may be disabled by setting \fBdoctest = false\fR for the +library in the manifest. +.sp +Binary targets are automatically built if there is an integration test or +benchmark being selected to test. This allows an integration +test to execute the binary to exercise and test its behavior. +The \fBCARGO_BIN_EXE_<name>\fR +\fIenvironment variable\fR <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 +\fI\f(BIenv\fI macro\fR <https://doc.rust\-lang.org/std/macro.env.html> to locate the +executable. +.sp +Passing target selection flags will test only the specified +targets. +.sp +Note that \fB\-\-bin\fR, \fB\-\-example\fR, \fB\-\-test\fR and \fB\-\-bench\fR flags also +support common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. 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. +.sp +\fB\-\-lib\fR +.RS 4 +Test the package\[cq]s library. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Test the specified binary. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-bins\fR +.RS 4 +Test all binary targets. +.RE +.sp +\fB\-\-example\fR \fIname\fR\[u2026] +.RS 4 +Test the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +.RE +.sp +\fB\-\-examples\fR +.RS 4 +Test all example targets. +.RE +.sp +\fB\-\-test\fR \fIname\fR\[u2026] +.RS 4 +Test the specified integration test. This flag may be specified +multiple times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-tests\fR +.RS 4 +Test all targets in test mode that have the \fBtest = true\fR manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the \fBtest\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-bench\fR \fIname\fR\[u2026] +.RS 4 +Test the specified benchmark. This flag may be specified multiple +times and supports common Unix glob patterns. +.RE +.sp +\fB\-\-benches\fR +.RS 4 +Test all targets in benchmark mode that have the \fBbench = true\fR +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the \fBbench\fR flag in the +manifest settings for the target. +.RE +.sp +\fB\-\-all\-targets\fR +.RS 4 +Test all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. +.RE +.sp +\fB\-\-doc\fR +.RS 4 +Test only the library\[cq]s documentation. This cannot be mixed with other +target options. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Test for the given architecture. The default is the host architecture. The general format of the triple is +\fB<arch><sub>\-<vendor>\-<sys>\-<abi>\fR\&. Run \fBrustc \-\-print target\-list\fR for a +list of supported targets. This flag may be specified multiple times. +.sp +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.sp +Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +\fIbuild cache\fR <https://doc.rust\-lang.org/cargo/guide/build\-cache.html> documentation for more details. +.RE +.sp +\fB\-r\fR, +\fB\-\-release\fR +.RS 4 +Test optimized artifacts with the \fBrelease\fR profile. +See also the \fB\-\-profile\fR option for choosing a specific profile by name. +.RE +.sp +\fB\-\-profile\fR \fIname\fR +.RS 4 +Test with the given profile. +See the \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/profiles.html> for more details on profiles. +.RE +.sp +\fB\-\-ignore\-rust\-version\fR +.RS 4 +Test the target even if the selected Rust compiler is older than the +required Rust version as configured in the project\[cq]s \fBrust\-version\fR field. +.RE +.sp +\fB\-\-timings=\fR\fIfmts\fR +.RS 4 +Output information how long each compilation takes, and track concurrency +information over time. Accepts an optional comma\-separated list of output +formats; \fB\-\-timings\fR without an argument will default to \fB\-\-timings=html\fR\&. +Specifying an output format (rather than the default) is unstable and requires +\fB\-Zunstable\-options\fR\&. Valid output formats: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhtml\fR (unstable, requires \fB\-Zunstable\-options\fR): Write a human\-readable file \fBcargo\-timing.html\fR to the +\fBtarget/cargo\-timings\fR 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. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR (unstable, requires \fB\-Zunstable\-options\fR): Emit machine\-readable JSON +information about timing information. +.RE +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fR \fIdirectory\fR +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +Defaults to \fBtarget\fR in the root of the workspace. +.RE +.SS "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 +\fB\-\-nocapture\fR to the test binaries: +.sp +.RS 4 +.nf +cargo test \-\- \-\-nocapture +.fi +.RE +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-message\-format\fR \fIfmt\fR +.RS 4 +The output format for diagnostic messages. Can be specified multiple times +and consists of comma\-separated values. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBhuman\fR (default): Display in a human\-readable text format. Conflicts with +\fBshort\fR and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. Conflicts with \fBhuman\fR +and \fBjson\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages> +for more details. Conflicts with \fBhuman\fR and \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains +the \[lq]short\[rq] rendering from rustc. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc\[cq]s default color +scheme. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo\[cq]s own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with \fBhuman\fR or \fBshort\fR\&. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SS "Miscellaneous Options" +The \fB\-\-jobs\fR argument affects the building of the test executable but does not +affect how many threads are used when running the tests. The Rust test harness +includes an option to control the number of threads used: +.sp +.RS 4 +.nf +cargo test \-j 2 \-\- \-\-test\-threads=2 +.fi +.RE +.sp +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fR \fIconfig value\fR <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. +.RE +.sp +\fB\-\-keep\-going\fR +.RS 4 +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 +\fB\-Zunstable\-options\fR\&. +.RE +.sp +\fB\-\-future\-incompat\-report\fR +.RS 4 +Displays a future\-incompat report for any future\-incompatible warnings +produced during execution of this command +.sp +See \fBcargo\-report\fR(1) +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Execute all the unit and integration tests of the current package: +.sp +.RS 4 +.nf +cargo test +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Run only tests whose names match against a filter string: +.sp +.RS 4 +.nf +cargo test name_filter +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Run only a specific test within a specific integration test: +.sp +.RS 4 +.nf +cargo test \-\-test int_test_name \-\- modname::test_name +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-bench\fR(1), \fItypes of tests\fR <https://doc.rust\-lang.org/cargo/reference/cargo\-targets.html#tests>, \fIhow to write tests\fR <https://doc.rust\-lang.org/rustc/tests/index.html> diff --git a/src/etc/man/cargo-tree.1 b/src/etc/man/cargo-tree.1 new file mode 100644 index 0000000..86077f5 --- /dev/null +++ b/src/etc/man/cargo-tree.1 @@ -0,0 +1,506 @@ +'\" t +.TH "CARGO\-TREE" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-tree \[em] Display a tree visualization of a dependency graph +.SH "SYNOPSIS" +\fBcargo tree\fR [\fIoptions\fR] +.SH "DESCRIPTION" +This command will display a tree of dependencies to the terminal. An example +of a simple project that depends on the \[lq]rand\[rq] package: +.sp +.RS 4 +.nf +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 +.fi +.RE +.sp +Packages marked with \fB(*)\fR have been \[lq]de\-duplicated\[rq]\&. The dependencies for the +package have already been shown elsewhere in the graph, and so are not +repeated. Use the \fB\-\-no\-dedupe\fR option to repeat the duplicates. +.sp +The \fB\-e\fR flag can be used to select the dependency kinds to display. The +\[lq]features\[rq] kind changes the output to display the features enabled by +each dependency. For example, \fBcargo tree \-e features\fR: +.sp +.RS 4 +.nf +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 +.fi +.RE +.sp +In this tree, \fBmyproject\fR depends on \fBlog\fR with the \fBserde\fR feature. \fBlog\fR in +turn depends on \fBcfg\-if\fR with \[lq]default\[rq] features. When using \fB\-e features\fR it +can be helpful to use \fB\-i\fR flag to show how the features flow into a package. +See the examples below for more detail. +.SS "Feature Unification" +This command shows a graph much closer to a feature\-unified graph Cargo will +build, rather than what you list in \fBCargo.toml\fR\&. For instance, if you specify +the same dependency in both \fB[dependencies]\fR and \fB[dev\-dependencies]\fR but with +different features on. This command may merge all features and show a \fB(*)\fR on +one of the dependency to indicate the duplicate. +.sp +As a result, for a mostly equivalent overview of what \fBcargo build\fR does, +\fBcargo tree \-e normal,build\fR is pretty close; for a mostly equivalent overview +of what \fBcargo test\fR does, \fBcargo tree\fR is pretty close. However, it doesn\[cq]t +guarantee the exact equivalence to what Cargo is going to build, since a +compilation is complex and depends on lots of different factors. +.sp +To learn more about feature unification, check out this +\fIdedicated section\fR <https://doc.rust\-lang.org/cargo/reference/features.html#feature\-unification>\&. +.SH "OPTIONS" +.SS "Tree Options" +.sp +\fB\-i\fR \fIspec\fR, +\fB\-\-invert\fR \fIspec\fR +.RS 4 +Show the reverse dependencies for the given package. This flag will invert +the tree and display the packages that depend on the given package. +.sp +Note that in a workspace, by default it will only display the package\[cq]s +reverse dependencies inside the tree of the workspace member in the current +directory. The \fB\-\-workspace\fR flag can be used to extend it so that it will +show the package\[cq]s reverse dependencies across the entire workspace. The \fB\-p\fR +flag can be used to display the package\[cq]s reverse dependencies only with the +subtree of the package given to \fB\-p\fR\&. +.RE +.sp +\fB\-\-prune\fR \fIspec\fR +.RS 4 +Prune the given package from the display of the dependency tree. +.RE +.sp +\fB\-\-depth\fR \fIdepth\fR +.RS 4 +Maximum display depth of the dependency tree. A depth of 1 displays the direct +dependencies, for example. +.RE +.sp +\fB\-\-no\-dedupe\fR +.RS 4 +Do not de\-duplicate repeated dependencies. Usually, when a package has already +displayed its dependencies, further occurrences will not re\-display its +dependencies, and will include a \fB(*)\fR to indicate it has already been shown. +This flag will cause those duplicates to be repeated. +.RE +.sp +\fB\-d\fR, +\fB\-\-duplicates\fR +.RS 4 +Show only dependencies which come in multiple versions (implies \fB\-\-invert\fR). +When used with the \fB\-p\fR flag, only shows duplicates within the subtree of the +given package. +.sp +It can be beneficial for build times and executable sizes to avoid building +that same package multiple times. This flag can help identify the offending +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. +.RE +.sp +\fB\-e\fR \fIkinds\fR, +\fB\-\-edges\fR \fIkinds\fR +.RS 4 +The dependency kinds to display. Takes a comma separated list of values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBall\fR \[em] Show all edge kinds. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnormal\fR \[em] Show normal dependencies. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBbuild\fR \[em] Show build dependencies. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBdev\fR \[em] Show development dependencies. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBfeatures\fR \[em] Show features enabled by each dependency. If this is the only +kind given, then it will automatically include the other dependency kinds. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBno\-normal\fR \[em] Do not include normal dependencies. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBno\-build\fR \[em] Do not include build dependencies. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBno\-dev\fR \[em] Do not include development dependencies. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBno\-proc\-macro\fR \[em] Do not include procedural macro dependencies. +.RE +.sp +The \fBnormal\fR, \fBbuild\fR, \fBdev\fR, and \fBall\fR dependency kinds cannot be mixed with +\fBno\-normal\fR, \fBno\-build\fR, or \fBno\-dev\fR dependency kinds. +.sp +The default is \fBnormal,build,dev\fR\&. +.RE +.sp +\fB\-\-target\fR \fItriple\fR +.RS 4 +Filter dependencies matching the given \fItarget triple\fR <https://doc.rust\-lang.org/cargo/appendix/glossary.html#target>\&. +The default is the host platform. Use the value \fBall\fR to include \fIall\fR targets. +.RE +.SS "Tree Formatting Options" +.sp +\fB\-\-charset\fR \fIcharset\fR +.RS 4 +Chooses the character set to use for the tree. Valid values are \[lq]utf8\[rq] or +\[lq]ascii\[rq]\&. Default is \[lq]utf8\[rq]\&. +.RE +.sp +\fB\-f\fR \fIformat\fR, +\fB\-\-format\fR \fIformat\fR +.RS 4 +Set the format string for each package. The default is \[lq]{p}\[rq]\&. +.sp +This is an arbitrary string which will be used to display each package. The following +strings will be replaced with the corresponding value: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB{p}\fR \[em] The package name. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB{l}\fR \[em] The package license. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB{r}\fR \[em] The package repository URL. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB{f}\fR \[em] Comma\-separated list of package features that are enabled. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB{lib}\fR \[em] The name, as used in a \fBuse\fR statement, of the package\[cq]s library. +.RE +.RE +.sp +\fB\-\-prefix\fR \fIprefix\fR +.RS 4 +Sets how each line is displayed. The \fIprefix\fR value can be one of: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBindent\fR (default) \[em] Shows each line indented as a tree. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBdepth\fR \[em] Show as a list, with the numeric depth printed before each entry. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnone\fR \[em] Show as a flat list. +.RE +.RE +.SS "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 +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. +.sp +The default members of a workspace can be set explicitly with the +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Display only the specified packages. See \fBcargo\-pkgid\fR(1) for the +SPEC format. This flag may be specified multiple times and supports common Unix +glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell accidentally +expanding glob patterns before Cargo handles them, you must use single quotes or +double quotes around each pattern. +.RE +.sp +\fB\-\-workspace\fR +.RS 4 +Display all members in the workspace. +.RE +.sp +\fB\-\-exclude\fR \fISPEC\fR\[u2026] +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-workspace\fR flag. This flag may be specified multiple times and supports +common Unix glob patterns like \fB*\fR, \fB?\fR and \fB[]\fR\&. However, to avoid your shell +accidentally expanding glob patterns before Cargo handles them, you must use +single quotes or double quotes around each pattern. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Feature Selection" +The feature flags allow you to control which features are enabled. When no +feature options are given, the \fBdefault\fR feature is activated for every +selected package. +.sp +See \fIthe features documentation\fR <https://doc.rust\-lang.org/cargo/reference/features.html#command\-line\-feature\-options> +for more details. +.sp +\fB\-F\fR \fIfeatures\fR, +\fB\-\-features\fR \fIfeatures\fR +.RS 4 +Space or comma separated list of features to activate. Features of workspace +members may be enabled with \fBpackage\-name/feature\-name\fR syntax. This flag may +be specified multiple times, which enables all specified features. +.RE +.sp +\fB\-\-all\-features\fR +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fR +.RS 4 +Do not activate the \fBdefault\fR feature of the selected packages. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Display the tree for the package in the current directory: +.sp +.RS 4 +.nf +cargo tree +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Display all the packages that depend on the \fBsyn\fR package: +.sp +.RS 4 +.nf +cargo tree \-i syn +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Show the features enabled on each package: +.sp +.RS 4 +.nf +cargo tree \-\-format "{p} {f}" +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Show all packages that are built multiple times. This can happen if multiple +semver\-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). +.sp +.RS 4 +.nf +cargo tree \-d +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 5.\h'+01'Explain why features are enabled for the \fBsyn\fR package: +.sp +.RS 4 +.nf +cargo tree \-e features \-i syn +.fi +.RE +.sp +The \fB\-e features\fR flag is used to show features. The \fB\-i\fR flag is used to +invert the graph so that it displays the packages that depend on \fBsyn\fR\&. An +example of what this would display: +.sp +.RS 4 +.nf +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" (*) +.fi +.RE +.sp +To read this graph, you can follow the chain for each feature from the root +to see why it is included. For example, the \[lq]full\[rq] feature is added by the +\fBrustversion\fR crate which is included from \fBmyproject\fR (with the default +features), and \fBmyproject\fR is the package selected on the command\-line. All +of the other \fBsyn\fR features are added by the \[lq]default\[rq] feature (\[lq]quote\[rq] is +added by \[lq]printing\[rq] and \[lq]proc\-macro\[rq], both of which are default features). +.sp +If you\[cq]re having difficulty cross\-referencing the de\-duplicated \fB(*)\fR +entries, try with the \fB\-\-no\-dedupe\fR flag to get the full output. +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-uninstall.1 b/src/etc/man/cargo-uninstall.1 new file mode 100644 index 0000000..be35a81 --- /dev/null +++ b/src/etc/man/cargo-uninstall.1 @@ -0,0 +1,160 @@ +'\" t +.TH "CARGO\-UNINSTALL" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-uninstall \[em] Remove a Rust binary +.SH "SYNOPSIS" +\fBcargo uninstall\fR [\fIoptions\fR] [\fIspec\fR\[u2026]] +.SH "DESCRIPTION" +This command removes a package installed with \fBcargo\-install\fR(1). The \fIspec\fR +argument is a package ID specification of the package to remove (see +\fBcargo\-pkgid\fR(1)). +.sp +By default all binaries are removed for a crate but the \fB\-\-bin\fR and +\fB\-\-example\fR flags can be used to only remove particular binaries. +.sp +The installation root is determined, in order of precedence: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB\-\-root\fR option +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR environment variable +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html> +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR environment variable +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR +.RE +.SH "OPTIONS" +.SS "Install Options" +.sp +\fB\-p\fR, +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Package to uninstall. +.RE +.sp +\fB\-\-bin\fR \fIname\fR\[u2026] +.RS 4 +Only uninstall the binary \fIname\fR\&. +.RE +.sp +\fB\-\-root\fR \fIdir\fR +.RS 4 +Directory to uninstall packages from. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Uninstall a previously installed package. +.sp +.RS 4 +.nf +cargo uninstall ripgrep +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-install\fR(1) diff --git a/src/etc/man/cargo-update.1 b/src/etc/man/cargo-update.1 new file mode 100644 index 0000000..29e630f --- /dev/null +++ b/src/etc/man/cargo-update.1 @@ -0,0 +1,217 @@ +'\" t +.TH "CARGO\-UPDATE" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-update \[em] Update dependencies as recorded in the local lock file +.SH "SYNOPSIS" +\fBcargo update\fR [\fIoptions\fR] +.SH "DESCRIPTION" +This command will update dependencies in the \fBCargo.lock\fR file to the latest +version. If the \fBCargo.lock\fR file does not exist, it will be created with the +latest available versions. +.SH "OPTIONS" +.SS "Update Options" +.sp +\fB\-p\fR \fIspec\fR\[u2026], +\fB\-\-package\fR \fIspec\fR\[u2026] +.RS 4 +Update only the specified packages. This flag may be specified +multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format. +.sp +If packages are specified with the \fB\-p\fR flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions. +.sp +If \fB\-p\fR is not specified, all dependencies are updated. +.RE +.sp +\fB\-\-aggressive\fR +.RS 4 +When used with \fB\-p\fR, dependencies of \fIspec\fR are forced to update as well. +Cannot be used with \fB\-\-precise\fR\&. +.RE +.sp +\fB\-\-precise\fR \fIprecise\fR +.RS 4 +When used with \fB\-p\fR, allows you to specify a specific version number to set +the package to. If the package comes from a git repository, this can be a git +revision (such as a SHA hash or tag). +.RE +.sp +\fB\-w\fR, +\fB\-\-workspace\fR +.RS 4 +Attempt to update only packages defined in the workspace. Other packages +are updated only if they don\[cq]t already exist in the lockfile. This +option is useful for updating \fBCargo.lock\fR after you\[cq]ve changed version +numbers in \fBCargo.toml\fR\&. +.RE +.sp +\fB\-\-dry\-run\fR +.RS 4 +Displays what would be updated, but doesn\[cq]t actually write the lockfile. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Update all dependencies in the lockfile: +.sp +.RS 4 +.nf +cargo update +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Update only specific dependencies: +.sp +.RS 4 +.nf +cargo update \-p foo \-p bar +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Set a specific dependency to a specific version: +.sp +.RS 4 +.nf +cargo update \-p foo \-\-precise 1.2.3 +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1) diff --git a/src/etc/man/cargo-vendor.1 b/src/etc/man/cargo-vendor.1 new file mode 100644 index 0000000..bc8f9ee --- /dev/null +++ b/src/etc/man/cargo-vendor.1 @@ -0,0 +1,208 @@ +'\" t +.TH "CARGO\-VENDOR" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-vendor \[em] Vendor all dependencies locally +.SH "SYNOPSIS" +\fBcargo vendor\fR [\fIoptions\fR] [\fIpath\fR] +.SH "DESCRIPTION" +This cargo subcommand will vendor all crates.io and git dependencies for a +project into the specified directory at \fB<path>\fR\&. After this command completes +the vendor directory specified by \fB<path>\fR will contain all remote sources from +dependencies specified. Additional manifests beyond the default one can be +specified with the \fB\-s\fR option. +.sp +The \fBcargo vendor\fR command will also print out the configuration necessary +to use the vendored sources, which you will need to add to \fB\&.cargo/config.toml\fR\&. +.SH "OPTIONS" +.SS "Vendor Options" +.sp +\fB\-s\fR \fImanifest\fR, +\fB\-\-sync\fR \fImanifest\fR +.RS 4 +Specify an extra \fBCargo.toml\fR manifest to workspaces which should also be +vendored and synced to the output. May be specified multiple times. +.RE +.sp +\fB\-\-no\-delete\fR +.RS 4 +Don\[cq]t delete the \[lq]vendor\[rq] directory when vendoring, but rather keep all +existing contents of the vendor directory +.RE +.sp +\fB\-\-respect\-source\-config\fR +.RS 4 +Instead of ignoring \fB[source]\fR configuration by default in \fB\&.cargo/config.toml\fR +read it and use it when downloading crates from crates.io, for example +.RE +.sp +\fB\-\-versioned\-dirs\fR +.RS 4 +Normally versions are only added to disambiguate multiple versions of the +same package. This option causes all directories in the \[lq]vendor\[rq] 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. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Vendor all dependencies into a local \[lq]vendor\[rq] folder +.sp +.RS 4 +.nf +cargo vendor +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Vendor all dependencies into a local \[lq]third\-party/vendor\[rq] folder +.sp +.RS 4 +.nf +cargo vendor third\-party/vendor +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Vendor the current workspace as well as another to \[lq]vendor\[rq] +.sp +.RS 4 +.nf +cargo vendor \-s ../path/to/Cargo.toml +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-verify-project.1 b/src/etc/man/cargo-verify-project.1 new file mode 100644 index 0000000..a85e191 --- /dev/null +++ b/src/etc/man/cargo-verify-project.1 @@ -0,0 +1,167 @@ +'\" t +.TH "CARGO\-VERIFY\-PROJECT" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-verify\-project \[em] Check correctness of crate manifest +.SH "SYNOPSIS" +\fBcargo verify\-project\fR [\fIoptions\fR] +.SH "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: +.sp +.RS 4 +.nf +{"success":"true"} +.fi +.RE +.sp +An invalid workspace will display: +.sp +.RS 4 +.nf +{"invalid":"human\-readable error message"} +.fi +.RE +.SH "OPTIONS" +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: The workspace is OK. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB1\fR: The workspace is invalid. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Check the current workspace for errors: +.sp +.RS 4 +.nf +cargo verify\-project +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-package\fR(1) diff --git a/src/etc/man/cargo-version.1 b/src/etc/man/cargo-version.1 new file mode 100644 index 0000000..6f1f463 --- /dev/null +++ b/src/etc/man/cargo-version.1 @@ -0,0 +1,52 @@ +'\" t +.TH "CARGO\-VERSION" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-version \[em] Show version information +.SH "SYNOPSIS" +\fBcargo version\fR [\fIoptions\fR] +.SH "DESCRIPTION" +Displays the version of Cargo. +.SH "OPTIONS" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Display additional version information. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Display the version: +.sp +.RS 4 +.nf +cargo version +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'The version is also available via flags: +.sp +.RS 4 +.nf +cargo \-\-version +cargo \-V +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Display extra version information: +.sp +.RS 4 +.nf +cargo \-Vv +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1 new file mode 100644 index 0000000..22d62b8 --- /dev/null +++ b/src/etc/man/cargo-yank.1 @@ -0,0 +1,168 @@ +'\" t +.TH "CARGO\-YANK" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo\-yank \[em] Remove a pushed crate from the index +.SH "SYNOPSIS" +\fBcargo yank\fR [\fIoptions\fR] \fIcrate\fR@\fIversion\fR +.br +\fBcargo yank\fR [\fIoptions\fR] \fB\-\-version\fR \fIversion\fR [\fIcrate\fR] +.SH "DESCRIPTION" +The yank command removes a previously published crate\[cq]s version from the +server\[cq]s index. This command does not delete any data, and the crate will +still be available for download via the registry\[cq]s download link. +.sp +Note that existing crates locked to a yanked version will still be able to +download the yanked version to use it. Cargo will, however, not allow any new +crates to be locked to any yanked version. +.sp +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). +.sp +If the crate name is not specified, it will use the package name from the +current directory. +.SH "OPTIONS" +.SS "Yank Options" +.sp +\fB\-\-vers\fR \fIversion\fR, +\fB\-\-version\fR \fIversion\fR +.RS 4 +The version to yank or un\-yank. +.RE +.sp +\fB\-\-undo\fR +.RS 4 +Undo a yank, putting a version back into the index. +.RE +.sp +\fB\-\-token\fR \fItoken\fR +.RS 4 +API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by \fBcargo\-login\fR(1)). +.sp +\fICargo config\fR <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 \fBCARGO_REGISTRY_TOKEN\fR environment +variable. Tokens for other registries may be specified with environment +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name +of the registry in all capital letters. +.RE +.sp +\fB\-\-index\fR \fIindex\fR +.RS 4 +The URL of the registry index to use. +.RE +.sp +\fB\-\-registry\fR \fIregistry\fR +.RS 4 +Name of the registry to use. Registry names are defined in \fICargo config +files\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Yank a crate from the index: +.sp +.RS 4 +.nf +cargo yank foo@1.0.7 +.fi +.RE +.RE +.SH "SEE ALSO" +\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 new file mode 100644 index 0000000..82da758 --- /dev/null +++ b/src/etc/man/cargo.1 @@ -0,0 +1,391 @@ +'\" t +.TH "CARGO" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +cargo \[em] The Rust package manager +.SH "SYNOPSIS" +\fBcargo\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR] +.br +\fBcargo\fR [\fIoptions\fR] \fB\-\-version\fR +.br +\fBcargo\fR [\fIoptions\fR] \fB\-\-list\fR +.br +\fBcargo\fR [\fIoptions\fR] \fB\-\-help\fR +.br +\fBcargo\fR [\fIoptions\fR] \fB\-\-explain\fR \fIcode\fR +.SH "DESCRIPTION" +This program is a package manager and build tool for the Rust language, +available at <https://rust\-lang.org>\&. +.SH "COMMANDS" +.SS "Build Commands" +\fBcargo\-bench\fR(1) +.br +\ \ \ \ Execute benchmarks of a package. +.sp +\fBcargo\-build\fR(1) +.br +\ \ \ \ Compile a package. +.sp +\fBcargo\-check\fR(1) +.br +\ \ \ \ Check a local package and all of its dependencies for errors. +.sp +\fBcargo\-clean\fR(1) +.br +\ \ \ \ Remove artifacts that Cargo has generated in the past. +.sp +\fBcargo\-doc\fR(1) +.br +\ \ \ \ Build a package\[cq]s documentation. +.sp +\fBcargo\-fetch\fR(1) +.br +\ \ \ \ Fetch dependencies of a package from the network. +.sp +\fBcargo\-fix\fR(1) +.br +\ \ \ \ Automatically fix lint warnings reported by rustc. +.sp +\fBcargo\-run\fR(1) +.br +\ \ \ \ Run a binary or example of the local package. +.sp +\fBcargo\-rustc\fR(1) +.br +\ \ \ \ Compile a package, and pass extra options to the compiler. +.sp +\fBcargo\-rustdoc\fR(1) +.br +\ \ \ \ Build a package\[cq]s documentation, using specified custom flags. +.sp +\fBcargo\-test\fR(1) +.br +\ \ \ \ Execute unit and integration tests of a package. +.SS "Manifest Commands" +\fBcargo\-generate\-lockfile\fR(1) +.br +\ \ \ \ Generate \fBCargo.lock\fR for a project. +.sp +\fBcargo\-locate\-project\fR(1) +.br +\ \ \ \ Print a JSON representation of a \fBCargo.toml\fR file\[cq]s location. +.sp +\fBcargo\-metadata\fR(1) +.br +\ \ \ \ Output the resolved dependencies of a package in machine\-readable format. +.sp +\fBcargo\-pkgid\fR(1) +.br +\ \ \ \ Print a fully qualified package specification. +.sp +\fBcargo\-tree\fR(1) +.br +\ \ \ \ Display a tree visualization of a dependency graph. +.sp +\fBcargo\-update\fR(1) +.br +\ \ \ \ Update dependencies as recorded in the local lock file. +.sp +\fBcargo\-vendor\fR(1) +.br +\ \ \ \ Vendor all dependencies locally. +.sp +\fBcargo\-verify\-project\fR(1) +.br +\ \ \ \ Check correctness of crate manifest. +.SS "Package Commands" +\fBcargo\-init\fR(1) +.br +\ \ \ \ Create a new Cargo package in an existing directory. +.sp +\fBcargo\-install\fR(1) +.br +\ \ \ \ Build and install a Rust binary. +.sp +\fBcargo\-new\fR(1) +.br +\ \ \ \ Create a new Cargo package. +.sp +\fBcargo\-search\fR(1) +.br +\ \ \ \ Search packages in crates.io. +.sp +\fBcargo\-uninstall\fR(1) +.br +\ \ \ \ Remove a Rust binary. +.SS "Publishing Commands" +\fBcargo\-login\fR(1) +.br +\ \ \ \ Save an API token from the registry locally. +.sp +\fBcargo\-owner\fR(1) +.br +\ \ \ \ Manage the owners of a crate on the registry. +.sp +\fBcargo\-package\fR(1) +.br +\ \ \ \ Assemble the local package into a distributable tarball. +.sp +\fBcargo\-publish\fR(1) +.br +\ \ \ \ Upload a package to the registry. +.sp +\fBcargo\-yank\fR(1) +.br +\ \ \ \ Remove a pushed crate from the index. +.SS "General Commands" +\fBcargo\-help\fR(1) +.br +\ \ \ \ Display help information about Cargo. +.sp +\fBcargo\-version\fR(1) +.br +\ \ \ \ Show version information. +.SH "OPTIONS" +.SS "Special Options" +.sp +\fB\-V\fR, +\fB\-\-version\fR +.RS 4 +Print version info and exit. If used with \fB\-\-verbose\fR, prints extra +information. +.RE +.sp +\fB\-\-list\fR +.RS 4 +List all installed Cargo subcommands. If used with \fB\-\-verbose\fR, prints extra +information. +.RE +.sp +\fB\-\-explain\fR \fIcode\fR +.RS 4 +Run \fBrustc \-\-explain CODE\fR which will print out a detailed explanation of an +error message (for example, \fBE0004\fR). +.RE +.SS "Display Options" +.sp +\fB\-v\fR, +\fB\-\-verbose\fR +.RS 4 +Use verbose output. May be specified twice for \[lq]very verbose\[rq] output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-q\fR, +\fB\-\-quiet\fR +.RS 4 +Do not print cargo log messages. +May also be specified with the \fBterm.quiet\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.sp +\fB\-\-color\fR \fIwhen\fR +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBauto\fR (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBalways\fR: Always display colors. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBnever\fR: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fR +\fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Manifest Options" +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR <https://doc.rust\-lang.org/cargo/reference/config.html>\&. +.RE +.SS "Common Options" +.sp +\fB+\fR\fItoolchain\fR +.RS 4 +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR <https://rust\-lang.github.io/rustup/overrides.html> +for more information about how toolchain overrides work. +.RE +.sp +\fB\-\-config\fR \fIKEY=VALUE\fR or \fIPATH\fR +.RS 4 +Overrides a Cargo configuration value. The argument should be in TOML syntax of \fBKEY=VALUE\fR, +or provided as a path to an extra configuration file. This flag may be specified multiple times. +See the \fIcommand\-line overrides section\fR <https://doc.rust\-lang.org/cargo/reference/config.html#command\-line\-overrides> for more information. +.RE +.sp +\fB\-C\fR \fIPATH\fR +.RS 4 +Changes the current working directory before executing any specified operations. This affects +things like where cargo looks by default for the project manifest (\fBCargo.toml\fR), as well as +the directories searched for discovering \fB\&.cargo/config.toml\fR, for example. +.sp +This option is only available on the \fInightly +channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html> and +requires the \fB\-Z unstable\-options\fR flag to enable (see +\fI#10098\fR <https://github.com/rust\-lang/cargo/issues/10098>). +.RE +.sp +\fB\-h\fR, +\fB\-\-help\fR +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fR \fIflag\fR +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. +.RE +.SH "ENVIRONMENT" +See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/environment\-variables.html> for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. +.RE +.SH "FILES" +\fB~/.cargo/\fR +.br +\ \ \ \ Default location for Cargo\[cq]s \[lq]home\[rq] directory where it +stores various files. The location can be changed with the \fBCARGO_HOME\fR +environment variable. +.sp +\fB$CARGO_HOME/bin/\fR +.br +\ \ \ \ Binaries installed by \fBcargo\-install\fR(1) will be located here. If using +\fIrustup\fR <https://rust\-lang.github.io/rustup/>, executables distributed with Rust are also located here. +.sp +\fB$CARGO_HOME/config.toml\fR +.br +\ \ \ \ The global configuration file. See \fIthe reference\fR <https://doc.rust\-lang.org/cargo/reference/config.html> +for more information about configuration files. +.sp +\fB\&.cargo/config.toml\fR +.br +\ \ \ \ Cargo automatically searches for a file named \fB\&.cargo/config.toml\fR in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file. +.sp +\fB$CARGO_HOME/credentials.toml\fR +.br +\ \ \ \ Private authentication information for logging in to a registry. +.sp +\fB$CARGO_HOME/registry/\fR +.br +\ \ \ \ This directory contains cached downloads of the registry index and any +downloaded dependencies. +.sp +\fB$CARGO_HOME/git/\fR +.br +\ \ \ \ This directory contains cached downloads of git dependencies. +.sp +Please note that the internal structure of the \fB$CARGO_HOME\fR directory is not +stable yet and may be subject to change. +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Build a local package and all of its dependencies: +.sp +.RS 4 +.nf +cargo build +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Build a package with optimizations: +.sp +.RS 4 +.nf +cargo build \-\-release +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Run tests for a cross\-compiled target: +.sp +.RS 4 +.nf +cargo test \-\-target i686\-unknown\-linux\-gnu +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Create a new package that builds an executable: +.sp +.RS 4 +.nf +cargo new foobar +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 5.\h'+01'Create a package in the current directory: +.sp +.RS 4 +.nf +mkdir foo && cd foo +cargo init . +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 6.\h'+01'Learn about a command\[cq]s options and usage: +.sp +.RS 4 +.nf +cargo help clean +.fi +.RE +.RE +.SH "BUGS" +See <https://github.com/rust\-lang/cargo/issues> for issues. +.SH "SEE ALSO" +\fBrustc\fR(1), \fBrustdoc\fR(1) |