From d931a95b82076a451b34f924b372e858d16f7af3 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 8 Dec 2018 16:44:37 -0800 Subject: [PATCH] New man pages. --- src/doc/Makefile | 28 + src/doc/asciidoc-extension.rb | 109 +++ src/doc/man/cargo-bench.adoc | 139 ++++ src/doc/man/cargo-build.adoc | 93 +++ src/doc/man/cargo-check.adoc | 86 ++ src/doc/man/cargo-clean.adoc | 75 ++ src/doc/man/cargo-doc.adoc | 94 +++ src/doc/man/cargo-fetch.adoc | 56 ++ src/doc/man/cargo-fix.adoc | 137 +++ src/doc/man/cargo-generate-lockfile.adoc | 48 ++ src/doc/man/cargo-help.adoc | 27 + src/doc/man/cargo-init.adoc | 54 ++ src/doc/man/cargo-install.adoc | 129 +++ src/doc/man/cargo-locate-project.adoc | 45 + src/doc/man/cargo-login.adoc | 54 ++ src/doc/man/cargo-metadata.adoc | 274 ++++++ src/doc/man/cargo-new.adoc | 49 ++ src/doc/man/cargo-owner.adoc | 79 ++ src/doc/man/cargo-package.adoc | 90 ++ src/doc/man/cargo-pkgid.adoc | 93 +++ src/doc/man/cargo-publish.adoc | 88 ++ src/doc/man/cargo-run.adoc | 88 ++ src/doc/man/cargo-rustc.adoc | 93 +++ src/doc/man/cargo-rustdoc.adoc | 95 +++ src/doc/man/cargo-search.adoc | 48 ++ src/doc/man/cargo-test.adoc | 146 ++++ src/doc/man/cargo-uninstall.adoc | 56 ++ src/doc/man/cargo-update.adoc | 77 ++ src/doc/man/cargo-verify-project.adoc | 56 ++ src/doc/man/cargo-version.adoc | 38 + src/doc/man/cargo-yank.adoc | 63 ++ src/doc/man/cargo.adoc | 217 +++++ src/doc/man/description-install-root.adoc | 7 + src/doc/man/description-new-authors.adoc | 24 + src/doc/man/description-one-target.adoc | 4 + src/doc/man/options-common.adoc | 7 + src/doc/man/options-display.adoc | 22 + src/doc/man/options-features.adoc | 16 + src/doc/man/options-index.adoc | 2 + src/doc/man/options-jobs.adoc | 5 + src/doc/man/options-locked.adoc | 10 + src/doc/man/options-manifest-path.adoc | 3 + src/doc/man/options-message-format.adoc | 6 + src/doc/man/options-new.adoc | 26 + src/doc/man/options-package.adoc | 7 + src/doc/man/options-packages.adoc | 18 + src/doc/man/options-profile.adoc | 6 + src/doc/man/options-registry.adoc | 5 + src/doc/man/options-release.adoc | 3 + src/doc/man/options-target-dir.adoc | 5 + src/doc/man/options-target-triple.adoc | 22 + src/doc/man/options-targets-lib-bin.adoc | 8 + src/doc/man/options-targets.adoc | 33 + src/doc/man/options-test.adoc | 8 + src/doc/man/options-token.adoc | 2 + src/doc/man/section-environment.adoc | 4 + src/doc/man/section-exit-status.adoc | 7 + src/doc/man/section-profiles.adoc | 24 + src/doc/src/SUMMARY.md | 36 + src/doc/src/commands/build-commands.md | 1 + src/doc/src/commands/cargo-bench.md | 3 + src/doc/src/commands/cargo-build.md | 3 + src/doc/src/commands/cargo-check.md | 3 + src/doc/src/commands/cargo-clean.md | 3 + src/doc/src/commands/cargo-doc.md | 3 + src/doc/src/commands/cargo-fetch.md | 3 + src/doc/src/commands/cargo-fix.md | 3 + .../src/commands/cargo-generate-lockfile.md | 3 + src/doc/src/commands/cargo-help.md | 3 + src/doc/src/commands/cargo-init.md | 3 + src/doc/src/commands/cargo-install.md | 3 + src/doc/src/commands/cargo-locate-project.md | 3 + src/doc/src/commands/cargo-login.md | 3 + src/doc/src/commands/cargo-metadata.md | 3 + src/doc/src/commands/cargo-new.md | 3 + src/doc/src/commands/cargo-owner.md | 3 + src/doc/src/commands/cargo-package.md | 3 + src/doc/src/commands/cargo-pkgid.md | 3 + src/doc/src/commands/cargo-publish.md | 3 + src/doc/src/commands/cargo-run.md | 3 + src/doc/src/commands/cargo-rustc.md | 3 + src/doc/src/commands/cargo-rustdoc.md | 3 + src/doc/src/commands/cargo-search.md | 3 + src/doc/src/commands/cargo-test.md | 3 + src/doc/src/commands/cargo-uninstall.md | 3 + src/doc/src/commands/cargo-update.md | 3 + src/doc/src/commands/cargo-verify-project.md | 3 + src/doc/src/commands/cargo-version.md | 3 + src/doc/src/commands/cargo-yank.md | 3 + src/doc/src/commands/command-common.html | 18 + src/doc/src/commands/general-commands.md | 1 + .../src/commands/generated/cargo-bench.html | 487 +++++++++++ .../src/commands/generated/cargo-build.html | 448 ++++++++++ .../src/commands/generated/cargo-check.html | 443 ++++++++++ .../src/commands/generated/cargo-clean.html | 254 ++++++ src/doc/src/commands/generated/cargo-doc.html | 410 +++++++++ .../src/commands/generated/cargo-fetch.html | 218 +++++ src/doc/src/commands/generated/cargo-fix.html | 522 ++++++++++++ .../generated/cargo-generate-lockfile.html | 166 ++++ .../src/commands/generated/cargo-help.html | 53 ++ .../src/commands/generated/cargo-init.html | 252 ++++++ .../src/commands/generated/cargo-install.html | 354 ++++++++ .../generated/cargo-locate-project.html | 152 ++++ .../src/commands/generated/cargo-login.html | 167 ++++ .../commands/generated/cargo-metadata.html | 427 ++++++++++ src/doc/src/commands/generated/cargo-new.html | 245 ++++++ .../src/commands/generated/cargo-owner.html | 205 +++++ .../src/commands/generated/cargo-package.html | 301 +++++++ .../src/commands/generated/cargo-pkgid.html | 241 ++++++ .../src/commands/generated/cargo-publish.html | 300 +++++++ src/doc/src/commands/generated/cargo-run.html | 379 +++++++++ .../src/commands/generated/cargo-rustc.html | 436 ++++++++++ .../src/commands/generated/cargo-rustdoc.html | 440 ++++++++++ .../src/commands/generated/cargo-search.html | 160 ++++ .../src/commands/generated/cargo-test.html | 545 ++++++++++++ .../commands/generated/cargo-uninstall.html | 183 ++++ .../src/commands/generated/cargo-update.html | 212 +++++ .../generated/cargo-verify-project.html | 174 ++++ .../src/commands/generated/cargo-version.html | 76 ++ .../src/commands/generated/cargo-yank.html | 181 ++++ src/doc/src/commands/generated/cargo.html | 433 ++++++++++ src/doc/src/commands/index.md | 3 + src/doc/src/commands/manifest-commands.md | 1 + src/doc/src/commands/package-commands.md | 1 + src/doc/src/commands/publishing-commands.md | 1 + src/etc/man/cargo-bench.1 | 676 ++++++++++++--- src/etc/man/cargo-build.1 | 611 +++++++++++--- src/etc/man/cargo-check.1 | 607 +++++++++++--- src/etc/man/cargo-clean.1 | 353 ++++++-- src/etc/man/cargo-doc.1 | 537 +++++++++--- src/etc/man/cargo-fetch.1 | 291 +++++-- src/etc/man/cargo-fix.1 | 578 +++++++++++++ src/etc/man/cargo-generate-lockfile.1 | 207 ++++- src/etc/man/cargo-help.1 | 75 ++ src/etc/man/cargo-init.1 | 418 ++++++++-- src/etc/man/cargo-install.1 | 555 +++++++++---- src/etc/man/cargo-locate-project.1 | 155 ++++ src/etc/man/cargo-login.1 | 206 ++++- src/etc/man/cargo-metadata.1 | 474 +++++++++-- src/etc/man/cargo-new.1 | 413 +++++++-- src/etc/man/cargo-owner.1 | 291 +++++-- src/etc/man/cargo-package.1 | 423 ++++++++-- src/etc/man/cargo-pkgid.1 | 334 ++++++-- src/etc/man/cargo-publish.1 | 416 ++++++++-- src/etc/man/cargo-run.1 | 507 +++++++++--- src/etc/man/cargo-rustc.1 | 605 +++++++++++--- src/etc/man/cargo-rustdoc.1 | 593 ++++++++++--- src/etc/man/cargo-search.1 | 206 ++++- src/etc/man/cargo-test.1 | 782 ++++++++++++++---- src/etc/man/cargo-uninstall.1 | 269 ++++-- src/etc/man/cargo-update.1 | 305 +++++-- src/etc/man/cargo-verify-project.1 | 178 ++++ src/etc/man/cargo-version.1 | 122 ++- src/etc/man/cargo-yank.1 | 239 ++++-- src/etc/man/cargo.1 | 645 ++++++++++----- 155 files changed, 21961 insertions(+), 2231 deletions(-) create mode 100644 src/doc/Makefile create mode 100644 src/doc/asciidoc-extension.rb create mode 100644 src/doc/man/cargo-bench.adoc create mode 100644 src/doc/man/cargo-build.adoc create mode 100644 src/doc/man/cargo-check.adoc create mode 100644 src/doc/man/cargo-clean.adoc create mode 100644 src/doc/man/cargo-doc.adoc create mode 100644 src/doc/man/cargo-fetch.adoc create mode 100644 src/doc/man/cargo-fix.adoc create mode 100644 src/doc/man/cargo-generate-lockfile.adoc create mode 100644 src/doc/man/cargo-help.adoc create mode 100644 src/doc/man/cargo-init.adoc create mode 100644 src/doc/man/cargo-install.adoc create mode 100644 src/doc/man/cargo-locate-project.adoc create mode 100644 src/doc/man/cargo-login.adoc create mode 100644 src/doc/man/cargo-metadata.adoc create mode 100644 src/doc/man/cargo-new.adoc create mode 100644 src/doc/man/cargo-owner.adoc create mode 100644 src/doc/man/cargo-package.adoc create mode 100644 src/doc/man/cargo-pkgid.adoc create mode 100644 src/doc/man/cargo-publish.adoc create mode 100644 src/doc/man/cargo-run.adoc create mode 100644 src/doc/man/cargo-rustc.adoc create mode 100644 src/doc/man/cargo-rustdoc.adoc create mode 100644 src/doc/man/cargo-search.adoc create mode 100644 src/doc/man/cargo-test.adoc create mode 100644 src/doc/man/cargo-uninstall.adoc create mode 100644 src/doc/man/cargo-update.adoc create mode 100644 src/doc/man/cargo-verify-project.adoc create mode 100644 src/doc/man/cargo-version.adoc create mode 100644 src/doc/man/cargo-yank.adoc create mode 100644 src/doc/man/cargo.adoc create mode 100644 src/doc/man/description-install-root.adoc create mode 100644 src/doc/man/description-new-authors.adoc create mode 100644 src/doc/man/description-one-target.adoc create mode 100644 src/doc/man/options-common.adoc create mode 100644 src/doc/man/options-display.adoc create mode 100644 src/doc/man/options-features.adoc create mode 100644 src/doc/man/options-index.adoc create mode 100644 src/doc/man/options-jobs.adoc create mode 100644 src/doc/man/options-locked.adoc create mode 100644 src/doc/man/options-manifest-path.adoc create mode 100644 src/doc/man/options-message-format.adoc create mode 100644 src/doc/man/options-new.adoc create mode 100644 src/doc/man/options-package.adoc create mode 100644 src/doc/man/options-packages.adoc create mode 100644 src/doc/man/options-profile.adoc create mode 100644 src/doc/man/options-registry.adoc create mode 100644 src/doc/man/options-release.adoc create mode 100644 src/doc/man/options-target-dir.adoc create mode 100644 src/doc/man/options-target-triple.adoc create mode 100644 src/doc/man/options-targets-lib-bin.adoc create mode 100644 src/doc/man/options-targets.adoc create mode 100644 src/doc/man/options-test.adoc create mode 100644 src/doc/man/options-token.adoc create mode 100644 src/doc/man/section-environment.adoc create mode 100644 src/doc/man/section-exit-status.adoc create mode 100644 src/doc/man/section-profiles.adoc create mode 100644 src/doc/src/commands/build-commands.md create mode 100644 src/doc/src/commands/cargo-bench.md create mode 100644 src/doc/src/commands/cargo-build.md create mode 100644 src/doc/src/commands/cargo-check.md create mode 100644 src/doc/src/commands/cargo-clean.md create mode 100644 src/doc/src/commands/cargo-doc.md create mode 100644 src/doc/src/commands/cargo-fetch.md create mode 100644 src/doc/src/commands/cargo-fix.md create mode 100644 src/doc/src/commands/cargo-generate-lockfile.md create mode 100644 src/doc/src/commands/cargo-help.md create mode 100644 src/doc/src/commands/cargo-init.md create mode 100644 src/doc/src/commands/cargo-install.md create mode 100644 src/doc/src/commands/cargo-locate-project.md create mode 100644 src/doc/src/commands/cargo-login.md create mode 100644 src/doc/src/commands/cargo-metadata.md create mode 100644 src/doc/src/commands/cargo-new.md create mode 100644 src/doc/src/commands/cargo-owner.md create mode 100644 src/doc/src/commands/cargo-package.md create mode 100644 src/doc/src/commands/cargo-pkgid.md create mode 100644 src/doc/src/commands/cargo-publish.md create mode 100644 src/doc/src/commands/cargo-run.md create mode 100644 src/doc/src/commands/cargo-rustc.md create mode 100644 src/doc/src/commands/cargo-rustdoc.md create mode 100644 src/doc/src/commands/cargo-search.md create mode 100644 src/doc/src/commands/cargo-test.md create mode 100644 src/doc/src/commands/cargo-uninstall.md create mode 100644 src/doc/src/commands/cargo-update.md create mode 100644 src/doc/src/commands/cargo-verify-project.md create mode 100644 src/doc/src/commands/cargo-version.md create mode 100644 src/doc/src/commands/cargo-yank.md create mode 100644 src/doc/src/commands/command-common.html create mode 100644 src/doc/src/commands/general-commands.md create mode 100644 src/doc/src/commands/generated/cargo-bench.html create mode 100644 src/doc/src/commands/generated/cargo-build.html create mode 100644 src/doc/src/commands/generated/cargo-check.html create mode 100644 src/doc/src/commands/generated/cargo-clean.html create mode 100644 src/doc/src/commands/generated/cargo-doc.html create mode 100644 src/doc/src/commands/generated/cargo-fetch.html create mode 100644 src/doc/src/commands/generated/cargo-fix.html create mode 100644 src/doc/src/commands/generated/cargo-generate-lockfile.html create mode 100644 src/doc/src/commands/generated/cargo-help.html create mode 100644 src/doc/src/commands/generated/cargo-init.html create mode 100644 src/doc/src/commands/generated/cargo-install.html create mode 100644 src/doc/src/commands/generated/cargo-locate-project.html create mode 100644 src/doc/src/commands/generated/cargo-login.html create mode 100644 src/doc/src/commands/generated/cargo-metadata.html create mode 100644 src/doc/src/commands/generated/cargo-new.html create mode 100644 src/doc/src/commands/generated/cargo-owner.html create mode 100644 src/doc/src/commands/generated/cargo-package.html create mode 100644 src/doc/src/commands/generated/cargo-pkgid.html create mode 100644 src/doc/src/commands/generated/cargo-publish.html create mode 100644 src/doc/src/commands/generated/cargo-run.html create mode 100644 src/doc/src/commands/generated/cargo-rustc.html create mode 100644 src/doc/src/commands/generated/cargo-rustdoc.html create mode 100644 src/doc/src/commands/generated/cargo-search.html create mode 100644 src/doc/src/commands/generated/cargo-test.html create mode 100644 src/doc/src/commands/generated/cargo-uninstall.html create mode 100644 src/doc/src/commands/generated/cargo-update.html create mode 100644 src/doc/src/commands/generated/cargo-verify-project.html create mode 100644 src/doc/src/commands/generated/cargo-version.html create mode 100644 src/doc/src/commands/generated/cargo-yank.html create mode 100644 src/doc/src/commands/generated/cargo.html create mode 100644 src/doc/src/commands/index.md create mode 100644 src/doc/src/commands/manifest-commands.md create mode 100644 src/doc/src/commands/package-commands.md create mode 100644 src/doc/src/commands/publishing-commands.md create mode 100644 src/etc/man/cargo-fix.1 create mode 100644 src/etc/man/cargo-help.1 create mode 100644 src/etc/man/cargo-locate-project.1 create mode 100644 src/etc/man/cargo-verify-project.1 diff --git a/src/doc/Makefile b/src/doc/Makefile new file mode 100644 index 00000000000..fbae6620574 --- /dev/null +++ b/src/doc/Makefile @@ -0,0 +1,28 @@ +# This Makefile is used to build the Cargo man pages. +# +# The source for the man pages are located in src/doc/man in Asciidoctor +# format. See https://asciidoctor.org/ for more information. +# +# Just run `make` and it will generate the man pages in src/etc/man and the +# HTML pages in src/doc/src/commands/generated. +# +# There are some Asciidoctor extensions, see the file `asciidoc-extensions.rb` +# for the documentation. + +MAN_SOURCE = $(sort $(wildcard man/cargo*.adoc)) +COMMANDS = $(notdir $(MAN_SOURCE)) +HTML = $(patsubst %.adoc,src/commands/generated/%.html,$(COMMANDS)) +MAN_LOCATION = ../etc/man +MAN = $(patsubst %.adoc,$(MAN_LOCATION)/%.1,$(COMMANDS)) +ASCIIDOCOPTS = -r ./asciidoc-extension.rb +OTHER_DEPS = asciidoc-extension.rb $(filter-out $(MAN_SOURCE),$(sort $(wildcard man/*.adoc))) + +all: commands-html man +commands-html: $(HTML) +man: $(MAN) + +$(HTML): src/commands/generated/%.html : man/%.adoc asciidoc-extension.rb $(OTHER_DEPS) + asciidoctor $(ASCIIDOCOPTS) -s $< -o $@ + +$(MAN): $(MAN_LOCATION)/%.1 : man/%.adoc $(OTHER_DEPS) + asciidoctor $(ASCIIDOCOPTS) -b manpage $< -o $@ diff --git a/src/doc/asciidoc-extension.rb b/src/doc/asciidoc-extension.rb new file mode 100644 index 00000000000..6e662639c1f --- /dev/null +++ b/src/doc/asciidoc-extension.rb @@ -0,0 +1,109 @@ +require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal' + +include Asciidoctor + +# An inline macro that generates links to related man pages. +# +# Usage +# +# man:gittutorial[7] +# +class ManInlineMacro < Extensions::InlineMacroProcessor + use_dsl + + named :man + name_positional_attributes 'volnum' + + def process parent, target, attrs + manname = target + suffix = if (volnum = attrs['volnum']) + "(#{volnum})" + else + nil + end + text = %(#{manname}#{suffix}) + if parent.document.basebackend? 'html' + parent.document.register :links, target + if manname == 'rustc' + html_target = 'https://doc.rust-lang.org/rustc/index.html' + elsif manname == 'rustdoc' + html_target = 'https://doc.rust-lang.org/rustdoc/index.html' + elsif manname == 'cargo' + html_target = 'commands/index.html' + else + html_target = %(commands/#{manname}.html) + end + %(#{(create_anchor parent, text, type: :link, target: html_target).render}) + elsif parent.document.backend == 'manpage' + %(\x1b\\fB#{manname}\x1b\\fP#{suffix}) + else + text + end + end +end + +# Creates a link to something in the cargo documentation. +# +# For HTML this creates a relative link (using mdbook's 0.1's base-style +# links). For the man page it gives a direct link to doc.rust-lang.org. +# +# Usage +# +# linkcargo:reference/manifest.html[the manifest] +# +class LinkCargoInlineMacro < Extensions::InlineMacroProcessor + use_dsl + + named :linkcargo + name_positional_attributes 'text' + + def process parent, target, attrs + text = attrs['text'] + if parent.document.basebackend? 'html' + parent.document.register :links, target + %(#{(create_anchor parent, text, type: :link, target: target).render}) + elsif parent.document.backend == 'manpage' + target = %(https://doc.rust-lang.org/cargo/#{target}) + %(#{(create_anchor parent, text, type: :link, target: target).render}) + else + %(#{text} <#{target}>) + end + end +end + +# Backticks in the manpage renderer use the CR font (courier), but in most +# cases in a terminal this doesn't look any different. Instead, use bold which +# should follow man page conventions better. +class MonoPostprocessor < Extensions::Postprocessor + def process document, output + if document.basebackend? 'manpage' + output = output.gsub(/\\f\(CR/, '\\fB') + end + output + end +end + +# General utility for converting text. Example: +# +# convert:lowercase[{somevar}] +class ConvertInlineMacro < Extensions::InlineMacroProcessor + use_dsl + + named :convert + name_positional_attributes 'text' + + def process parent, target, attrs + text = attrs['text'] + case target + when 'lowercase' + text.downcase + end + end +end + +Extensions.register :uri_schemes do + inline_macro ManInlineMacro + inline_macro LinkCargoInlineMacro + inline_macro ConvertInlineMacro + postprocessor MonoPostprocessor +end diff --git a/src/doc/man/cargo-bench.adoc b/src/doc/man/cargo-bench.adoc new file mode 100644 index 00000000000..3ac56c6e180 --- /dev/null +++ b/src/doc/man/cargo-bench.adoc @@ -0,0 +1,139 @@ += cargo-bench(1) +:doctype: manpage +:actionverb: Benchmark +:nouns: benchmarks + +== NAME + +cargo-bench - Execute benchmarks of a package + +== SYNOPSIS + +`cargo bench [_OPTIONS_] [BENCHNAME] [-- _BENCH-OPTIONS_]` + +== DESCRIPTION + +Compile and execute benchmarks. + +The benchmark filtering argument `BENCHNAME` and all the arguments following +the two dashes (`--`) are passed to the benchmark binaries and thus to +_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If +you're passing arguments to both Cargo and the binary, the ones after `--` go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of `cargo bench -- --help`. As an example, this will +run only the benchmark named `foo` (and skip other similarly named benchmarks +like `foobar`): + + cargo bench -- foo --exact + +Benchmarks are built with the `--test` option to `rustc` which creates an +executable with a `main` function that automatically runs all functions +annotated with the `#[bench]` attribute. The libtest harness may be disabled +by setting `harness = false` in the target manifest settings, in which case +your code will need to provide its own `main` function to handle running +benchmarks. + +== OPTIONS + +=== Benchmark Options + +include::options-test.adoc[] + +=== Package Selection + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo bench` will build the +following targets of the selected packages: + +- lib – used to link with binaries and benchmarks +- bins (only if benchmark targets are built and required features are + available) +- lib as a benchmark +- bins as benchmarks +- benchmark targets + +The default behavior can be changed by setting the `bench` flag for the target +in the manifest settings. Setting examples to `bench = true` will build and +run the example as a benchmark. Setting targets to `bench = false` will stop +them from being benchmarked by default. Target selection options that take a +target by name ignore the `bench` flag and will always benchmark the given +target. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +By default the Rust test harness hides output from benchmark execution to keep +results readable. Benchmark output can be recovered (e.g. for debugging) by +passing `--nocapture` to the benchmark binaries: + + cargo bench -- --nocapture + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +The `--jobs` argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread. + +include::options-jobs.adoc[] + +== PROFILES + +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +linkcargo:reference/manifest.html#the-profile-sections[the reference] +for more details. + +Benchmarks are always built with the `bench` profile. Binary and lib targets +are built separately as benchmarks with the `bench` profile. Library targets +are built with the `release` profiles when linked to binaries and benchmarks. +Dependencies use the `release` profile. + +If you need a debug build of a benchmark, try building it with +man:cargo-build[1] which will use the `test` profile which is by default +unoptimized and includes debug information. You can then run the debug-enabled +benchmark manually. + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build and execute all the benchmarks of the current package: + + cargo bench + +. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +== SEE ALSO +man:cargo[1], man:cargo-test[1] diff --git a/src/doc/man/cargo-build.adoc b/src/doc/man/cargo-build.adoc new file mode 100644 index 00000000000..7776c8393cd --- /dev/null +++ b/src/doc/man/cargo-build.adoc @@ -0,0 +1,93 @@ += cargo-build(1) +:doctype: manpage +:actionverb: Build + +== NAME + +cargo-build - Compile the current package + +== SYNOPSIS + +`cargo build [_OPTIONS_]` + +== DESCRIPTION + +Compile local packages and all of their dependencies. + +== OPTIONS + +=== Package Selection + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo build` will build all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +*--out-dir* _DIRECTORY_:: + Copy final artifacts to this directory. ++ +This option is unstable and available only on the nightly channel and requires +the `-Z unstable-options` flag to enable. + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +*--build-plan*:: + Outputs a series of JSON messages to stdout that indicate the commands to + run the build. ++ +This option is unstable and available only on the nightly channel and requires +the `-Z unstable-options` flag to enable. + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build the local package and all of its dependencies: + + cargo build + +. Build with optimizations: + + cargo build --release + +== SEE ALSO +man:cargo[1], man:cargo-rustc[1] diff --git a/src/doc/man/cargo-check.adoc b/src/doc/man/cargo-check.adoc new file mode 100644 index 00000000000..c9dfd58b49c --- /dev/null +++ b/src/doc/man/cargo-check.adoc @@ -0,0 +1,86 @@ += cargo-check(1) +:doctype: manpage +:actionverb: Check + +== NAME + +cargo-check - Check the current package + +== SYNOPSIS + +`cargo check [_OPTIONS_]` + +== DESCRIPTION + +Check a local package and all of its dependencies for errors. This will +essentially compile the packages without performing the final step of code +generation, which is faster than running `cargo build`. The compiler will save +metadata files to disk so that future runs will reuse them if the source has +not been modified. + +== OPTIONS + +=== Package Selection + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo check` will check all +binary and library targets of the selected packages. Binaries are skipped if +they have `required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +include::options-profile.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Check the local package for errors: + + cargo check + +. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +== SEE ALSO +man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-clean.adoc b/src/doc/man/cargo-clean.adoc new file mode 100644 index 00000000000..b03a88db88f --- /dev/null +++ b/src/doc/man/cargo-clean.adoc @@ -0,0 +1,75 @@ += cargo-clean(1) +:doctype: manpage +:actionverb: Clean + +== NAME + +cargo-clean - Remove generated artifacts + +== SYNOPSIS + +`cargo clean [_OPTIONS_]` + +== DESCRIPTION + +Remove artifacts from the target directory that Cargo has generated in the +past. + +With no options, `cargo clean` will delete the entire target directory. + +== OPTIONS + +=== Package Selection + +When no packages are selected, all packages and all dependencies in the +workspace are cleaned. + +*-p* _SPEC_...:: +*--package* _SPEC_...:: + Clean only the specified packages. This flag may be specified + multiple times. See man:cargo-pkgid[1] for the SPEC format. + +=== Clean Options + +*--doc*:: + This option will cause `cargo clean` to remove only the `doc` directory in + the target directory. + +*--release*:: + Clean all artifacts that were built with the `release` or `bench` + profiles. + +include::options-target-dir.adoc[] + +include::options-target-triple.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Remove the entire target directory: + + cargo clean + +. Remove only the release artifacts: + + cargo clean --release + +== SEE ALSO +man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-doc.adoc b/src/doc/man/cargo-doc.adoc new file mode 100644 index 00000000000..bc79d875ef3 --- /dev/null +++ b/src/doc/man/cargo-doc.adoc @@ -0,0 +1,94 @@ += cargo-doc(1) +:doctype: manpage +:actionverb: Document + +== NAME + +cargo-doc - Build a package's documentation + +== SYNOPSIS + +`cargo doc [_OPTIONS_]` + +== DESCRIPTION + +Build the documentation for the local package and all dependencies. The output +is placed in `target/doc` in rustdoc's usual format. + +== OPTIONS + +=== Documentation Options + +*--open*:: + Open the docs in a browser after building them. + +*--no-deps*:: + Do not build documentation for dependencies. + +*--document-private-items*:: + Include non-public items in the documentation. + +=== Package Selection + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo doc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +The default behavior can be changed by setting `doc = false` for the target in +the manifest settings. Using target selection options will ignore the `doc` +flag and will always document the given target. + +include::options-targets-lib-bin.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build the local package documentation and its dependencies and output to +`target/doc`. + + cargo doc + +== SEE ALSO +man:cargo[1], man:cargo-rustdoc[1], man:rustdoc[1] diff --git a/src/doc/man/cargo-fetch.adoc b/src/doc/man/cargo-fetch.adoc new file mode 100644 index 00000000000..536ab4903fe --- /dev/null +++ b/src/doc/man/cargo-fetch.adoc @@ -0,0 +1,56 @@ += cargo-fetch(1) +:doctype: manpage +:actionverb: Fetch + +== NAME + +cargo-fetch - Fetch dependencies of a package from the network + +== SYNOPSIS + +`cargo fetch [_OPTIONS_]` + +== DESCRIPTION + +If a `Cargo.lock` file is available, this command will ensure that all of the +git dependencies and/or registry dependencies are downloaded and locally +available. Subsequent Cargo commands never touch the network after a `cargo +fetch` unless the lock file changes. + +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. + +If `--target` is not specified, then all target dependencies are fetched. + +== OPTIONS + +=== Fetch options + +include::options-target-triple.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Fetch all dependencies: + + cargo fetch + +== SEE ALSO +man:cargo[1], man:cargo-update[1], man:cargo-generate-lockfile[1] diff --git a/src/doc/man/cargo-fix.adoc b/src/doc/man/cargo-fix.adoc new file mode 100644 index 00000000000..95f2e361a32 --- /dev/null +++ b/src/doc/man/cargo-fix.adoc @@ -0,0 +1,137 @@ += cargo-fix(1) +:doctype: manpage +:actionverb: Fix + +== NAME + +cargo-fix - Automatically fix lint warnings reported by rustc + +== SYNOPSIS + +`cargo fix [_OPTIONS_]` + +== DESCRIPTION + +This Cargo subcommand will automatically take rustc's suggestions from +diagnostics like warnings and apply them to your source code. This is intended +to help automate tasks that rustc itself already knows how to tell you to fix! +The `cargo fix` subcommand is also being developed for the Rust 2018 edition +to provide code the ability to easily opt-in to the new edition without having +to worry about any breakage. + +Executing `cargo fix` will under the hood execute man:cargo-check[1]. Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you'd like to prepare for the 2018 edition, you can do so by +executing: + + cargo fix --edition + +which behaves the same as `cargo check --all-targets`. Similarly if you'd like +to fix code for different platforms you can do: + + cargo fix --edition --target x86_64-pc-windows-gnu + +or if your crate has optional features: + + cargo fix --edition --no-default-features --features foo + +If you encounter any problems with `cargo fix` or otherwise have any questions +or feature requests please don't hesitate to file an issue at +https://github.com/rust-lang/cargo + +== OPTIONS + +=== Fix options + +*--broken-code*:: + Fix code even if it already has compiler errors. This is useful if `cargo + fix` fails to apply the changes. It will apply the changes and leave the + broken code in the working directory for you to inspect and manually fix. + +*--edition*:: + Apply changes that will update the code to the latest edition. This will + not update the edition in the `Cargo.toml` manifest, which must be updated + manually. + +*--edition-idioms*:: + Apply suggestions that will update code to the preferred style for the + current edition. + +*--allow-no-vcs*:: + Fix code even if a VCS was not detected. + +*--allow-dirty*:: + Fix code even if the working directory has changes. + +*--allow-staged*:: + Fix code even if the working directory has staged changes. + +=== Package Selection + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo fix` will fix all targets +(`--all-targets` implied). Binaries are skipped if they have +`required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +include::options-profile.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Apply compiler suggestions to the local package: + + cargo fix + +. Convert a 2015 edition to 2018: + + cargo fix --edition + +. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +== SEE ALSO +man:cargo[1], man:cargo-check[1] diff --git a/src/doc/man/cargo-generate-lockfile.adoc b/src/doc/man/cargo-generate-lockfile.adoc new file mode 100644 index 00000000000..beb94736f33 --- /dev/null +++ b/src/doc/man/cargo-generate-lockfile.adoc @@ -0,0 +1,48 @@ += cargo-generate-lockfile(1) +:doctype: manpage + +== NAME + +cargo-generate-lockfile - Generate the lockfile for a package + +== SYNOPSIS + +`cargo generate-lockfile [_OPTIONS_]` + +== DESCRIPTION + +This command will create the `Cargo.lock` lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt if there are any +manifest changes or dependency updates. + +See also man:cargo-update[1] which is also capable of creating a `Cargo.lock` +lockfile and has more options for controlling update behavior. + +== OPTIONS + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +== SEE ALSO +man:cargo[1], man:cargo-update[1] diff --git a/src/doc/man/cargo-help.adoc b/src/doc/man/cargo-help.adoc new file mode 100644 index 00000000000..87f7e481878 --- /dev/null +++ b/src/doc/man/cargo-help.adoc @@ -0,0 +1,27 @@ += cargo-help(1) +:doctype: manpage + +== NAME + +cargo-help - Get help for a Cargo command + +== SYNOPSIS + +`cargo help [_SUBCOMMAND_]` + +== DESCRIPTION + +Prints a help message for the given command. + +== EXAMPLES + +. Get help for a command: + + cargo help build + +. Help is also available with the `--help` flag: + + cargo build --help + +== SEE ALSO +man:cargo[1] diff --git a/src/doc/man/cargo-init.adoc b/src/doc/man/cargo-init.adoc new file mode 100644 index 00000000000..773ed37376a --- /dev/null +++ b/src/doc/man/cargo-init.adoc @@ -0,0 +1,54 @@ += cargo-init(1) +:doctype: manpage + +== NAME + +cargo-init - Create a new Cargo package in an existing directory + +== SYNOPSIS + +`cargo init [_OPTIONS_] [_PATH_]` + +== DESCRIPTION + +This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory. + +If there are typically-named Rust source files already in the directory, those +will be used. If not, then a sample `src/main.rs` file will be created, or +`src/lib.rs` if `--lib` is passed. + +If the directory is not already in a VCS repository, then a new repository +is created (see `--vcs` below). + +include::description-new-authors.adoc[] + +See man:cargo-new[1] for a similar command which will create a new package in +a new directory. + +== OPTIONS + +=== Init Options + +include::options-new.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create a binary Cargo package in the current directory: + + cargo init + +== SEE ALSO +man:cargo[1], man:cargo-new[1] diff --git a/src/doc/man/cargo-install.adoc b/src/doc/man/cargo-install.adoc new file mode 100644 index 00000000000..3abea34effb --- /dev/null +++ b/src/doc/man/cargo-install.adoc @@ -0,0 +1,129 @@ += cargo-install(1) +:doctype: manpage +:actionverb: Install + +== NAME + +cargo-install - Build and install a Rust binary + +== SYNOPSIS + +[%hardbreaks] +`cargo install [_OPTIONS_] _CRATE_...` +`cargo install [_OPTIONS_] --path _PATH_` +`cargo install [_OPTIONS_] --git _URL_ [_CRATE_...]` +`cargo install [_OPTIONS_] --list` + +== DESCRIPTION + +This command manages Cargo's local set of installed binary crates. Only packages +which have `\[[bin]]` targets can be installed, and all binaries are installed into +the installation root's `bin` folder. + +include::description-install-root.adoc[] + +There are multiple sources from which a crate can be installed. The default +location is crates.io but the `--git` and `--path` flags can change this +source. If the source contains more than one package (such as crates.io or a +git repository with multiple crates) the _CRATE_ argument is required to +indicate which crate should be installed. + +Crates from crates.io can optionally specify the version they wish to install +via the `--version` flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the `--bin` argument can selectively install only +one of them, and if you'd rather install examples the `--example` argument can +be used as well. + +If the source is crates.io or `--git` then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the `CARGO_TARGET_DIR` environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems. + +== OPTIONS + +=== Install Options + +*--vers* _VERSION_:: +*--version* _VERSION_:: + Specify a version to install from crates.io. + +*--git* _URL_:: + Git URL to install the specified crate from. + +*--branch* _BRANCH_:: + Branch to use when installing from git. + +*--tag* _TAG_:: + Tag to use when installing from git. + +*--rev* _SHA_:: + Specific commit to use when installing from git. + +*--path* _PATH_:: + Filesystem path to local crate to install. + +*--list*:: + List all installed packages and their versions. + +*-f*:: +*--force*:: + Force overwriting existing crates or binaries. This can be used to + reinstall or upgrade a crate. + + +*--bin* _NAME_...:: + Install only the specified binary. + +*--bins*:: + Install all binaries. + +*--example* _NAME_...:: + Install only the specified example. + +*--examples*:: + Install all examples. + +*--root* _DIR_:: + Directory to install packages into. + +include::options-registry.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +*--debug*:: + Build in debug mode instead of release mode. + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Install a package from crates.io: + + cargo install ripgrep + +. Reinstall or upgrade a package: + + cargo install ripgrep --force + +== SEE ALSO +man:cargo[1], man:cargo-uninstall[1], man:cargo-search[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-locate-project.adoc b/src/doc/man/cargo-locate-project.adoc new file mode 100644 index 00000000000..a099e6bcb2b --- /dev/null +++ b/src/doc/man/cargo-locate-project.adoc @@ -0,0 +1,45 @@ += cargo-locate-project(1) +:doctype: manpage + +== NAME + +cargo-locate-project - Print a JSON representation of a Cargo.toml file's location + +== SYNOPSIS + +`cargo locate-project [_OPTIONS_]` + +== DESCRIPTION + +This command will print a JSON object to stdout with the full path to the +`Cargo.toml` manifest. + +See also man:cargo-metadata[1] which is capable of returning the path to a +workspace root. + +== OPTIONS + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Display the path to the manifest based on the current directory: + + cargo locate-project + +== SEE ALSO +man:cargo[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-login.adoc b/src/doc/man/cargo-login.adoc new file mode 100644 index 00000000000..ac25955cef6 --- /dev/null +++ b/src/doc/man/cargo-login.adoc @@ -0,0 +1,54 @@ += cargo-login(1) +:doctype: manpage + +== NAME + +cargo-login - Save an API token from the registry locally + +== SYNOPSIS + +`cargo login [_OPTIONS_] [_TOKEN_]` + +== DESCRIPTION + +This command will save the API token to disk so that commands that require +authentication (such as man:cargo-publish[1]) will be automatically +authenticated. The token is saved in `$CARGO_HOME/credentials`. `CARGO_HOME` +defaults to `.cargo` in your home directory. + +If the _TOKEN_ argument is not specified, it will be read from stdin. + +The API token for crates.io may be retrieved from https://crates.io/me. + +Take care to keep the token secret, it should not be shared with anyone else. + +== OPTIONS + +=== Login Options + +*--host* _HOST_:: + Host to set the token for. This option does not affect the behavior of the + login command, and only affects the message displayed. + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Save the API token to disk: + + cargo login + +== SEE ALSO +man:cargo[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-metadata.adoc b/src/doc/man/cargo-metadata.adoc new file mode 100644 index 00000000000..6c4d90d7db9 --- /dev/null +++ b/src/doc/man/cargo-metadata.adoc @@ -0,0 +1,274 @@ += cargo-metadata(1) +:doctype: manpage +:source-highlighter: highlightjs + +== NAME + +cargo-metadata - Machine-readable metadata about the current package + +== SYNOPSIS + +`cargo metadata [_OPTIONS_]` + +== DESCRIPTION + +Output the resolved dependencies of a package, the concrete used versions +including overrides, in JSON to stdout. + +It is recommended to include the `--format-version` flag to future-proof +your code to ensure the output is in the format you are expecting. + +See the link:https://crates.io/crates/cargo_metadata[cargo_metadata crate] +for a Rust API for reading the metadata. + +== OUTPUT FORMAT + +The output has the following format: + +[source,javascript] +---- +{ + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. */ + "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)" + } + ], + /* 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"] + } + ], + /* 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 + } + } + }, + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe " + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018" + } + ], + /* 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, with the concrete versions and features + selected. The set depends on the enabled features. + This is null if --no-deps is specified. + */ + "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. + 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 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" +} +---- + +== OPTIONS + +=== Output Options + +*--no-deps*:: + Output information only about the workspace members and don't fetch + dependencies. + +*--format-version* _VERSION_:: + Specify the version of the output format to use. Currently `1` is the only + possible value. + +include::options-features.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Output JSON about the current package: + + cargo metadata --format-version=1 + +== SEE ALSO +man:cargo[1] diff --git a/src/doc/man/cargo-new.adoc b/src/doc/man/cargo-new.adoc new file mode 100644 index 00000000000..eebb6cff882 --- /dev/null +++ b/src/doc/man/cargo-new.adoc @@ -0,0 +1,49 @@ += cargo-new(1) +:doctype: manpage + +== NAME + +cargo-new - Create a new Cargo package + +== SYNOPSIS + +`cargo new [_OPTIONS_] _PATH_` + +== DESCRIPTION + +This command will create a new Cargo package in the given directory. This +includes a simple template with a `Cargo.toml` manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see `--vcs` below). + +include::description-new-authors.adoc[] + +See man:cargo-init[1] for a similar command which will create a new manifest +in an existing directory. + +== OPTIONS + +=== New Options + +include::options-new.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create a binary Cargo package in the given directory: + + cargo new foo + +== SEE ALSO +man:cargo[1], man:cargo-init[1] diff --git a/src/doc/man/cargo-owner.adoc b/src/doc/man/cargo-owner.adoc new file mode 100644 index 00000000000..25be145589b --- /dev/null +++ b/src/doc/man/cargo-owner.adoc @@ -0,0 +1,79 @@ += cargo-owner(1) +:doctype: manpage + +== NAME + +cargo-owner - Manage the owners of a crate on the registry + +== SYNOPSIS + +[%hardbreaks] +`cargo owner [_OPTIONS_] --add _LOGIN_ [_CRATE_]` +`cargo owner [_OPTIONS_] --remove _LOGIN_ [_CRATE_]` +`cargo owner [_OPTIONS_] --list [_CRATE_]` + +== DESCRIPTION + +This command will modify the owners for a crate on the registry. Owners of a +crate can upload new versions and yank old versions. Non-team owners can also +modify the set of owners, so take care! + +This command requires you to be authenticated with either the `--token` option +or using man:cargo-login[1]. + +If the crate name is not specified, it will use the package name from the +current directory. + +See linkcargo:reference/publishing.html#cargo-owner[the reference] for more +information about owners and publishing. + +== OPTIONS + +=== Owner Options + +*-a*:: +*--add* _LOGIN_...:: + Add the given user or team as an owner. + +*-r*:: +*--remove* _LOGIN_...:: + Remove the given user or team as an owner. + +*-l*:: +*--list*:: + List owners of a crate. + +include::options-token.adoc[] + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. List owners of a package: + + cargo owner --list foo + +. Add an owner to a package: + + cargo owner --add username foo + +. Remove an owner from a package: + + cargo owner --remove username foo + +== SEE ALSO +man:cargo[1], man:cargo-login[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-package.adoc b/src/doc/man/cargo-package.adoc new file mode 100644 index 00000000000..845626fea96 --- /dev/null +++ b/src/doc/man/cargo-package.adoc @@ -0,0 +1,90 @@ += cargo-package(1) +:doctype: manpage +:actionverb: Package + +== NAME + +cargo-package - Assemble the local package into a distributable tarball + +== SYNOPSIS + +`cargo package [_OPTIONS_]` + +== DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory. The resulting file will +be stored in the `target/package` directory. This performs the following +steps: + +. Load and check the current workspace, performing some basic checks. + - Path dependencies are not allowed unless they have a version key. Cargo + will ignore the path key for dependencies in published packages. +. Create the compressed `.crate` file. + - The original `Cargo.toml` file is rewritten and normalized. + - A `.cargo_vcs_info.json` file is included that contains information + about the current VCS checkout hash if available (not included with + `--allow-dirty`). +. Extract the `.crate` file and build it to verify it can build. +. Check that build scripts did not modify any source files. + +The list of files included can be controlled with the `include` and `exclude` +fields in the manifest. + +See linkcargo:reference/publishing.html[the reference] for more details about +packaging and publishing. + +== OPTIONS + +=== Package Options + +*-l*:: +*--list*:: + Print files included in a package without making one. + +*--no-verify*:: + Don't verify the contents by building them. + +*--no-metadata*:: + Ignore warnings about a lack of human-usable metadata (such as the + description or the license). + +*--allow-dirty*:: + Allow working directories with uncommitted VCS changes to be packaged. + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-target-dir.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Create a compressed `.crate` file of the current package: + + cargo package + +== SEE ALSO +man:cargo[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-pkgid.adoc b/src/doc/man/cargo-pkgid.adoc new file mode 100644 index 00000000000..646254a205e --- /dev/null +++ b/src/doc/man/cargo-pkgid.adoc @@ -0,0 +1,93 @@ += cargo-pkgid(1) +:doctype: manpage + +== NAME + +cargo-pkgid - Print a fully qualified package specification + +== SYNOPSIS + +`cargo pkgid [_OPTIONS_] [_SPEC_]` + +== DESCRIPTION + +Given a _SPEC_ argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if _SPEC_ is ambiguous as to which package it refers to in +the dependency graph. If no _SPEC_ is given, then the specifier for the local +package is printed. + +This command requires that a lockfile is available and dependencies have been +fetched. + +A package specifier consists of a name, version, and source URL. You are +allowed to use partial specifiers to succinctly match a specific package as +long as it matches only one package. The format of a _SPEC_ can be one of the +following: + +[%autowidth] +.SPEC Query Format +|=== +|SPEC Structure |Example SPEC + +|__NAME__ +|`bitflags` + +|__NAME__``:``__VERSION__ +|`bitflags:1.0.4` + +|__URL__ +|`https://github.com/rust-lang/cargo` + +|__URL__``#``__VERSION__ +|`https://github.com/rust-lang/cargo#0.33.0` + +|__URL__``#``__NAME__ +|`https://github.com/rust-lang/crates.io-index#bitflags` + +|__URL__``#``__NAME__``:``__VERSION__ +|`https://github.com/rust-lang/cargo#crates-io:0.21.0` +|=== + +== OPTIONS + +=== Package Selection + +*-p* _SPEC_:: +*--package* _SPEC_:: + Get the package ID for the given package instead of the current package. + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Retrieve package specification for `foo` package: + + cargo pkgid foo + +. Retrieve package specification for version 1.0.0 of `foo`: + + cargo pkgid foo:1.0.0 + +. Retrieve package specification for `foo` from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +== SEE ALSO +man:cargo[1], man:cargo-generate-lockfile[1], man:cargo-metadata[1] diff --git a/src/doc/man/cargo-publish.adoc b/src/doc/man/cargo-publish.adoc new file mode 100644 index 00000000000..759d78b35c4 --- /dev/null +++ b/src/doc/man/cargo-publish.adoc @@ -0,0 +1,88 @@ += cargo-publish(1) +:doctype: manpage +:actionverb: Publish + +== NAME + +cargo-publish - Upload a package to the registry + +== SYNOPSIS + +`cargo package [_OPTIONS_]` + +== DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory and upload it to a +registry. The default registry is https://crates.io. This performs the +following steps: + +. Performs a few checks, including: + - No `[patch]` sections are allowed in the manifest. + - Checks the `package.publish` key in the manifest for restrictions on which + registries you are allowed to publish to. +. Create a `.crate` file by following the steps in man:cargo-package[1]. +. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + +This command requires you to be authenticated with either the `--token` option +or using man:cargo-login[1]. + +See linkcargo:reference/publishing.html[the reference] for more details about +packaging and publishing. + +== OPTIONS + +=== Publish Options + +*--dry-run*:: + Perform all checks without uploading. + +include::options-token.adoc[] + +*--no-verify*:: + Don't verify the contents by building them. + +*--allow-dirty*:: + Allow working directories with uncommitted VCS changes to be packaged. + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-target-dir.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Publish the current package: + + cargo publish + +== SEE ALSO +man:cargo[1], man:cargo-package[1], man:cargo-login[1] diff --git a/src/doc/man/cargo-run.adoc b/src/doc/man/cargo-run.adoc new file mode 100644 index 00000000000..8869256a1f3 --- /dev/null +++ b/src/doc/man/cargo-run.adoc @@ -0,0 +1,88 @@ += cargo-run(1) +:doctype: manpage +:actionverb: Run + +== NAME + +cargo-run - Run the current package + +== SYNOPSIS + +`cargo run [_OPTIONS_] [-- _ARGS_]` + +== DESCRIPTION + +Build the the main binary of the local package (`src/main.rs`) and run it. + +All the arguments following the two dashes (`--`) are passed to the binary to +run. If you're passing arguments to both Cargo and the binary, the ones after +`--` go to the binary, the ones before go to Cargo. + +== OPTIONS + +=== Package Selection + +include::options-package.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo run` will run the binary +target. If there are multiple binary targets, you must pass a target flag to +choose one. + +*--bin* _NAME_:: + Run the specified binary. + +*--example* _NAME_:: + Run the specified example. + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build the local package and run its main target: + + cargo run + +. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +== SEE ALSO +man:cargo[1], man:cargo-build[1] diff --git a/src/doc/man/cargo-rustc.adoc b/src/doc/man/cargo-rustc.adoc new file mode 100644 index 00000000000..4bfe1f2dcc3 --- /dev/null +++ b/src/doc/man/cargo-rustc.adoc @@ -0,0 +1,93 @@ += cargo-rustc(1) +:doctype: manpage +:actionverb: Build + +== NAME + +cargo-rustc - Compile the current package, and pass extra options to the compiler + +== SYNOPSIS + +`cargo rustc [_OPTIONS_] [-- _ARGS_]` + +== DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be compiled along with all of its dependencies. The specified +_ARGS_ will all be passed to the final compiler invocation, not any of the +dependencies. Note that the compiler will still unconditionally receive +arguments such as `-L`, `--extern`, and `--crate-type`, and the specified +_ARGS_ will simply be added to the compiler invocation. + +See https://doc.rust-lang.org/rustc/index.html for documentation on rustc +flags. + +include::description-one-target.adoc[] +To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` +environment variable or the `build.rustflags` +linkcargo:reference/config.html[config value]. + +== OPTIONS + +=== Package Selection + +include::options-package.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo rustc` will build all +binary and library targets of the selected package. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + +. Try an experimental flag on the nightly compiler, such as this which prints + the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + +== SEE ALSO +man:cargo[1], man:cargo-build[1], man:rustc[1] diff --git a/src/doc/man/cargo-rustdoc.adoc b/src/doc/man/cargo-rustdoc.adoc new file mode 100644 index 00000000000..03b888d515a --- /dev/null +++ b/src/doc/man/cargo-rustdoc.adoc @@ -0,0 +1,95 @@ += cargo-rustdoc(1) +:doctype: manpage +:actionverb: Document + +== NAME + +cargo-rustdoc - Build a package's documentation, using specified custom flags + +== SYNOPSIS + +`cargo rustdoc [_OPTIONS_] [-- _ARGS_]` + +== DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be documented with the specified _ARGS_ being passed to the +final rustdoc invocation. Dependencies will not be documented as part of this +command. Note that rustdoc will still unconditionally receive arguments such +as `-L`, `--extern`, and `--crate-type`, and the specified _ARGS_ will simply +be added to the rustdoc invocation. + +See https://doc.rust-lang.org/rustdoc/index.html for documentation on rustdoc +flags. + +include::description-one-target.adoc[] +To pass flags to all rustdoc processes spawned by Cargo, use the +`RUSTDOCFLAGS` environment variable or the `build.rustdocflags` configuration +option. + +== OPTIONS + +=== Documentation Options + +*--open*:: + Open the docs in a browser after building them. + +=== Package Selection + +include::options-package.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo rustdoc` will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +`required-features` that are missing. + +include::options-targets.adoc[] + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +== SEE ALSO +man:cargo[1], man:cargo-doc[1], man:rustdoc[1] diff --git a/src/doc/man/cargo-search.adoc b/src/doc/man/cargo-search.adoc new file mode 100644 index 00000000000..6c18a950aa3 --- /dev/null +++ b/src/doc/man/cargo-search.adoc @@ -0,0 +1,48 @@ += cargo-search(1) +:doctype: manpage + +== NAME + +cargo-search - Search packages in crates.io + +== SYNOPSIS + +`cargo search [_OPTIONS_] [_QUERY_...]` + +== DESCRIPTION + +This performs a textual search for crates on https://crates.io. The matching +crates will be displayed along with their description in TOML format suitable +for copying into a `Cargo.toml` manifest. + +== OPTIONS + +=== Search Options + +*--limit* _LIMIT_:: + Limit the number of results (default: 10, max: 100). + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Search for a package from crates.io: + + cargo search serde + +== SEE ALSO +man:cargo[1], man:cargo-install[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo-test.adoc b/src/doc/man/cargo-test.adoc new file mode 100644 index 00000000000..b8a7baf0a82 --- /dev/null +++ b/src/doc/man/cargo-test.adoc @@ -0,0 +1,146 @@ += cargo-test(1) +:doctype: manpage +:actionverb: Test +:nouns: tests + +== NAME + +cargo-test - Execute unit and integration tests of a package + +== SYNOPSIS + +`cargo test [_OPTIONS_] [TESTNAME] [-- _TEST-OPTIONS_]` + +== DESCRIPTION + +Compile and execute unit and integration tests. + +The test filtering argument `TESTNAME` and all the arguments following the two +dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's +built in unit-test and micro-benchmarking framework). If you're passing +arguments to both Cargo and the binary, the ones after `--` go to the binary, +the ones before go to Cargo. For details about libtest's arguments see the +output of `cargo test -- --help`. As an example, this will run all tests with +`foo` in their name on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + +Tests are built with the `--test` option to `rustc` which creates an +executable with a `main` function that automatically runs all functions +annotated with the `#[test]` attribute in multiple threads. The libtest +harness may be disabled by setting `harness = false` in the target manifest +settings, in which case your code will need to provide its own `main` function +to handle running tests. + +Documentation tests are also run by default, which is handled by `rustdoc`. It +extracts code samples from documentation comments and executes them. + +== OPTIONS + +=== Test Options + +include::options-test.adoc[] + +=== Package Selection + +include::options-packages.adoc[] + +=== Target Selection + +When no target selection options are given, `cargo test` will build the +following targets of the selected packages: + +- lib – used to link with binaries, examples, integration tests, and doc tests +- bins (only if integration tests are built and required features are + available) +- examples – to ensure they compile +- lib as a unit test +- bins as unit tests +- integration tests +- doc tests for the lib target + +The default behavior can be changed by setting the `test` flag for the target +in the manifest settings. Setting examples to `test = true` will build and run +the example as a test. Setting targets to `test = false` will stop them from +being tested by default. Target selection options that take a target by name +ignore the `test` flag and will always test the given target. + +Doc tests for libraries may be disabled by setting `doctest = false` for the +library in the manifest. + +include::options-targets.adoc[] + +*--doc*:: + Test only the library's documentation. This cannot be mixed with other + target options. + +include::options-features.adoc[] + +=== Compilation Options + +include::options-target-triple.adoc[] + +include::options-release.adoc[] + +=== Output Options + +include::options-target-dir.adoc[] + +=== Display Options + +By default the Rust test harness hides output from test execution to keep +results readable. Test output can be recovered (e.g. for debugging) by passing +`--nocapture` to the test binaries: + + cargo test -- --nocapture + +include::options-display.adoc[] + +include::options-message-format.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +=== Miscellaneous Options + +The `--jobs` argument affects the building of the test executable but does not +affect how many threads are used when running the tests. The Rust test harness +includes an option to control the number of threads used: + + cargo test -j 2 -- --test-threads=2 + +include::options-jobs.adoc[] + +include::section-profiles.adoc[] + +Unit tests are separate executable artifacts which use the `test`/`bench` +profiles. Example targets are built the same as with `cargo build` (using the +`dev`/`release` profiles) unless you are building them with the test harness +(by setting `test = true` in the manifest or using the `--example` flag) in +which case they use the `test`/`bench` profiles. Library targets are built +with the `dev`/`release` profiles when linked to an integration test, binary, +or doctest. + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Execute all the unit and integration tests of the current package: + + cargo test + +. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +== SEE ALSO +man:cargo[1], man:cargo-bench[1] diff --git a/src/doc/man/cargo-uninstall.adoc b/src/doc/man/cargo-uninstall.adoc new file mode 100644 index 00000000000..81b89b167b6 --- /dev/null +++ b/src/doc/man/cargo-uninstall.adoc @@ -0,0 +1,56 @@ += cargo-uninstall(1) +:doctype: manpage + +== NAME + +cargo-uninstall - Remove a Rust binary + +== SYNOPSIS + +`cargo uninstall [_OPTIONS_] [_SPEC_...]` + +== DESCRIPTION + +This command removes a package installed with man:cargo-install[1]. The _SPEC_ +argument is a package ID specification of the package to remove (see +man:cargo-pkgid[1]). + +By default all binaries are removed for a crate but the `--bin` and +`--example` flags can be used to only remove particular binaries. + +include::description-install-root.adoc[] + +== OPTIONS + +=== Install Options + +*-p*:: +*--package* _SPEC_...:: + Package to uninstall. + +*--bin* _NAME_...:: + Only uninstall the binary _NAME_. + +*--root* _DIR_:: + Directory to uninstall packages from. + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Uninstall a previously installed package. + + cargo uninstall ripgrep + +== SEE ALSO +man:cargo[1], man:cargo-install[1] diff --git a/src/doc/man/cargo-update.adoc b/src/doc/man/cargo-update.adoc new file mode 100644 index 00000000000..0baa98903b9 --- /dev/null +++ b/src/doc/man/cargo-update.adoc @@ -0,0 +1,77 @@ += cargo-update(1) +:doctype: manpage + +== NAME + +cargo-update - Update dependencies as recorded in the local lock file + +== SYNOPSIS + +`cargo update [_OPTIONS_]` + +== DESCRIPTION + +This command will update dependencies in the `Cargo.lock` file to the latest +version. It requires that the `Cargo.lock` file already exists as generated +by commands such as man:cargo-build[1] or man:cargo-generate-lockfile[1]. + +== OPTIONS + +=== Update Options + +*-p* _SPEC_...:: +*--package* _SPEC_...:: + Update only the specified packages. This flag may be specified + multiple times. See man:cargo-pkgid[1] for the SPEC format. ++ +If packages are specified with the `-p` flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions. ++ +If `-p` is not specified, all dependencies are updated. + +*--aggressive*:: + When used with `-p`, dependencies of _SPEC_ are forced to update as well. + Cannot be used with `--precise`. + +*--precise* _PRECISE_:: + When used with `-p`, allows you to specify a specific version number to + set the package to. If the package comes from a git repository, this can + be a git revision (such as a SHA hash or tag). + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Update all dependencies in the lockfile: + + cargo update + +. Update only specific dependencies: + + cargo update -p foo -p bar + +. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +== SEE ALSO +man:cargo[1], man:cargo-generate-lockfile[1] diff --git a/src/doc/man/cargo-verify-project.adoc b/src/doc/man/cargo-verify-project.adoc new file mode 100644 index 00000000000..f6f9a044fdc --- /dev/null +++ b/src/doc/man/cargo-verify-project.adoc @@ -0,0 +1,56 @@ += cargo-verify-project(1) +:doctype: manpage + +== NAME + +cargo-verify-project - Check correctness of crate manifest + +== SYNOPSIS + +`cargo verify-project [_OPTIONS_]` + +== DESCRIPTION + +This command will parse the local manifest and check its validity. It emits a +JSON object with the result. A successful validation will display: + + {"success":"true"} + +An invalid workspace will display: + + {"invalid":"human-readable error message"} + +== OPTIONS + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-manifest-path.adoc[] + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +== Exit Status + +0:: + The workspace is OK. + +1:: + The workspace is invalid. + +== EXAMPLES + +. Check the current workspace for errors: + + cargo verify-project + +== SEE ALSO +man:cargo[1], man:cargo-package[1] diff --git a/src/doc/man/cargo-version.adoc b/src/doc/man/cargo-version.adoc new file mode 100644 index 00000000000..809ef68f8ea --- /dev/null +++ b/src/doc/man/cargo-version.adoc @@ -0,0 +1,38 @@ += cargo-version(1) +:doctype: manpage + +== NAME + +cargo-version - Show version information + +== SYNOPSIS + +`cargo version [_OPTIONS_]` + +== DESCRIPTION + +Displays the version of Cargo. + +== OPTIONS + +*-v*:: +*--verbose*:: + Display additional version information. + +== EXAMPLES + +. Display the version: + + cargo version + +. The version is also available via flags: + + cargo --version + cargo -V + +. Display extra version information: + + cargo -Vv + +== SEE ALSO +man:cargo[1] diff --git a/src/doc/man/cargo-yank.adoc b/src/doc/man/cargo-yank.adoc new file mode 100644 index 00000000000..0bb437bb116 --- /dev/null +++ b/src/doc/man/cargo-yank.adoc @@ -0,0 +1,63 @@ += cargo-yank(1) +:doctype: manpage + +== NAME + +cargo-yank - Remove a pushed crate from the index + +== SYNOPSIS + +`cargo yank [_OPTIONS_] --vers _VERSION_ [_CRATE_]` + +== DESCRIPTION + +The yank command removes a previously published crate's version from the +server's index. This command does not delete any data, and the crate will +still be available for download via the registry's download link. + +Note that existing crates locked to a yanked version will still be able to +download the yanked version to use it. Cargo will, however, not allow any new +crates to be locked to any yanked version. + +This command requires you to be authenticated with either the `--token` option +or using man:cargo-login[1]. + +If the crate name is not specified, it will use the package name from the +current directory. + +== OPTIONS + +=== Owner Options + +*--vers* _VERSION_:: + The version to yank or un-yank. + +*--undo*:: + Undo a yank, putting a version back into the index. + +include::options-token.adoc[] + +include::options-index.adoc[] + +include::options-registry.adoc[] + +=== Display Options + +include::options-display.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== EXAMPLES + +. Yank a crate from the index: + + cargo yank --vers 1.0.7 foo + +== SEE ALSO +man:cargo[1], man:cargo-login[1], man:cargo-publish[1] diff --git a/src/doc/man/cargo.adoc b/src/doc/man/cargo.adoc new file mode 100644 index 00000000000..69f879bac2c --- /dev/null +++ b/src/doc/man/cargo.adoc @@ -0,0 +1,217 @@ += cargo(1) +:doctype: manpage + +== NAME + +cargo - The Rust package manager + +== SYNOPSIS + +[%hardbreaks] +`cargo [_OPTIONS_] _COMMAND_ [_ARGS_]` +`cargo [_OPTIONS_] --version` +`cargo [_OPTIONS_] --list` +`cargo [_OPTIONS_] --help` +`cargo [_OPTIONS_] --explain _CODE_` + +== DESCRIPTION + +This program is a package manager and build tool for the Rust language, +available at . + +== COMMANDS + +=== Build Commands + +man:cargo-bench[1]:: + Execute benchmarks of a package. + +man:cargo-build[1]:: + Compile a package. + +man:cargo-check[1]:: + Check a local package and all of its dependencies for errors. + +man:cargo-clean[1]:: + Remove artifacts that Cargo has generated in the past. + +man:cargo-doc[1]:: + Build a package's documentation. + +man:cargo-fetch[1]:: + Fetch dependencies of a package from the network. + +man:cargo-fix[1]:: + Automatically fix lint warnings reported by rustc. + +man:cargo-run[1]:: + Run a binary of the local package. + +man:cargo-rustc[1]:: + Compile a package, and pass extra options to the compiler. + +man:cargo-rustdoc[1]:: + Build a package's documentation, using specified custom flags. + +man:cargo-test[1]:: + Execute unit and integration tests of a package. + +=== Manifest Commands + +man:cargo-generate-lockfile[1]:: + Generate `Cargo.lock` for a project. + +man:cargo-locate-project[1]:: + Print a JSON representation of a `Cargo.toml` file's location. + +man:cargo-metadata[1]:: + Output the resolved dependencies of a package, the concrete used versions + including overrides, in machine-readable format. + +man:cargo-pkgid[1]:: + Print a fully qualified package specification. + +man:cargo-update[1]:: + Update dependencies as recorded in the local lock file. + +man:cargo-verify-project[1]:: + Check correctness of crate manifest. + +=== Package Commands + +man:cargo-init[1]:: + Create a new Cargo package in an existing directory. + +man:cargo-install[1]:: + Build and install a Rust binary. + +man:cargo-new[1]:: + Create a new Cargo package. + +man:cargo-search[1]:: + Search packages in crates.io. + +man:cargo-uninstall[1]:: + Remove a Rust binary. + +=== Publishing Commands + +man:cargo-login[1]:: + Save an API token from the registry locally. + +man:cargo-owner[1]:: + Manage the owners of a crate on the registry. + +man:cargo-package[1]:: + Assemble the local package into a distributable tarball. + +man:cargo-publish[1]:: + Upload a package to the registry. + +man:cargo-yank[1]:: + Remove a pushed crate from the index. + +=== General Commands + +man:cargo-help[1]:: + Display help information about Cargo. + +man:cargo-version[1]:: + Show version information. + +== OPTIONS + +=== Special Options + +*-V*:: +*--version*:: + Print version info and exit. If used with `--verbose`, prints extra + information. + +*--list*:: + List all installed Cargo subcommands. If used with `--verbose`, prints + extra information. + +*--explain _CODE_*:: + Run `rustc --explain CODE` which will print out a detailed explanation of + an error message (for example, `E0004`). + +=== Display Options + +include::options-display.adoc[] + +=== Manifest Options + +include::options-locked.adoc[] + +=== Common Options + +include::options-common.adoc[] + +include::section-environment.adoc[] + +include::section-exit-status.adoc[] + +== FILES + +`~/.cargo/`:: + Default location for Cargo's "home" directory where it stores various + files. The location can be changed with the `CARGO_HOME` environment + variable. + +`$CARGO_HOME/bin/`:: + Binaries installed by man:cargo-install[1] will be located here. If using + rustup, executables distributed with Rust are also located here. + +`$CARGO_HOME/config`:: + The global configuration file. See linkcargo:reference/config.html[the reference] + for more information about configuration files. + +`.cargo/config`:: + Cargo automatically searches for a file named `.cargo/config` in the + current directory, and all parent directories. These configuration files + will be merged with the global configuration file. + +`$CARGO_HOME/credentials`:: + Private authentication information for logging in to a registry. + +`$CARGO_HOME/registry/`:: + This directory contains cached downloads of the registry index and any + downloaded dependencies. + +`$CARGO_HOME/git/`:: + This directory contains cached downloads of git dependencies. + +== EXAMPLES + +. Build a local package and all of its dependencies: + + cargo build + +. Build a package with optimizations: + + cargo build --release + +. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + +. Create a new package that builds an executable: + + cargo new foobar + +. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + +. Learn about a command's options and usage: + + cargo help clean + +== BUGS + +See https://github.com/rust-lang/cargo/issues for issues. + +== SEE ALSO +man:rustc[1], man:rustdoc[1] diff --git a/src/doc/man/description-install-root.adoc b/src/doc/man/description-install-root.adoc new file mode 100644 index 00000000000..d7773d3b20a --- /dev/null +++ b/src/doc/man/description-install-root.adoc @@ -0,0 +1,7 @@ +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo linkcargo:reference/config.html[config value] +- `CARGO_HOME` environment variable +- `$HOME/.cargo` diff --git a/src/doc/man/description-new-authors.adoc b/src/doc/man/description-new-authors.adoc new file mode 100644 index 00000000000..0435295b726 --- /dev/null +++ b/src/doc/man/description-new-authors.adoc @@ -0,0 +1,24 @@ +The "authors" field in the manifest is determined from the environment or +configuration settings. A name is required and is determined from (first match +wins): + +- `cargo-new.name` Cargo config value +- `CARGO_NAME` environment variable +- `GIT_AUTHOR_NAME` environment variable +- `GIT_COMMITTER_NAME` environment variable +- `user.name` git configuration value +- `USER` environment variable +- `USERNAME` environment variable +- `NAME` environment variable + +The email address is optional and is determined from: + +- `cargo-new.email` Cargo config value +- `CARGO_EMAIL` environment variable +- `GIT_AUTHOR_EMAIL` environment variable +- `GIT_COMMITTER_EMAIL` environment variable +- `user.email` git configuration value +- `EMAIL` environment variable + +See linkcargo:reference/config.html[the reference] for more information about +configuration files. diff --git a/src/doc/man/description-one-target.adoc b/src/doc/man/description-one-target.adoc new file mode 100644 index 00000000000..7af18131f5f --- /dev/null +++ b/src/doc/man/description-one-target.adoc @@ -0,0 +1,4 @@ +This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of `--lib`, `--bin`, etc, must be used to select which +target is compiled. diff --git a/src/doc/man/options-common.adoc b/src/doc/man/options-common.adoc new file mode 100644 index 00000000000..b8c2fce380c --- /dev/null +++ b/src/doc/man/options-common.adoc @@ -0,0 +1,7 @@ +*-h*:: +*--help*:: + Prints help information. + +*-Z* _FLAG_...:: + Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for + details. diff --git a/src/doc/man/options-display.adoc b/src/doc/man/options-display.adoc new file mode 100644 index 00000000000..cc2e2263398 --- /dev/null +++ b/src/doc/man/options-display.adoc @@ -0,0 +1,22 @@ +*-v*:: +*--verbose*:: + Use verbose output. May be specified twice for "very verbose" output which + includes extra output such as dependency warnings and build script output. + May also be specified with the `term.verbose` + linkcargo:reference/config.html[config value]. + +*-q*:: +*--quiet*:: + No output printed to stdout. + +*--color* _WHEN_:: + Control when colored output is used. Valid values: ++ +- `auto` (default): Automatically detect if color support is available on the + terminal. +- `always`: Always display colors. +- `never`: Never display colors. + ++ +May also be specified with the `term.color` +linkcargo:reference/config.html[config value]. diff --git a/src/doc/man/options-features.adoc b/src/doc/man/options-features.adoc new file mode 100644 index 00000000000..666ef21e4ec --- /dev/null +++ b/src/doc/man/options-features.adoc @@ -0,0 +1,16 @@ +=== Feature Selection + +When no feature options are given, the `default` feature is activated for +every selected package. + +*--features* _FEATURES_:: + Space or comma separated list of features to activate. These features only + apply to the current directory's package. Features of direct dependencies + may be enabled with `/` syntax. + +*--all-features*:: + Activate all available features of all selected packages. + +*--no-default-features*:: + Do not activate the `default` feature of the current directory's + package. diff --git a/src/doc/man/options-index.adoc b/src/doc/man/options-index.adoc new file mode 100644 index 00000000000..1321866bae7 --- /dev/null +++ b/src/doc/man/options-index.adoc @@ -0,0 +1,2 @@ +*--index* _INDEX_:: + The URL of the registry index to use. diff --git a/src/doc/man/options-jobs.adoc b/src/doc/man/options-jobs.adoc new file mode 100644 index 00000000000..9d817426ba1 --- /dev/null +++ b/src/doc/man/options-jobs.adoc @@ -0,0 +1,5 @@ +*-j* _N_:: +*--jobs* _N_:: + Number of parallel jobs to run. May also be specified with the + `build.jobs` linkcargo:reference/config.html[config value]. Defaults to + the number of CPUs. diff --git a/src/doc/man/options-locked.adoc b/src/doc/man/options-locked.adoc new file mode 100644 index 00000000000..e783f5fcd3b --- /dev/null +++ b/src/doc/man/options-locked.adoc @@ -0,0 +1,10 @@ +*--frozen*:: +*--locked*:: + Either of these flags requires that the `Cargo.lock` file is + up-to-date. If the lock file is missing, or it needs to be updated, Cargo will + exit with an error. The `--frozen` flag also prevents Cargo from + attempting to access the network to determine if it is out-of-date. ++ +These may be used in environments where you want to assert that the +`Cargo.lock` file is up-to-date (such as a CI build) or want to avoid network +access. diff --git a/src/doc/man/options-manifest-path.adoc b/src/doc/man/options-manifest-path.adoc new file mode 100644 index 00000000000..1bc4d80eb94 --- /dev/null +++ b/src/doc/man/options-manifest-path.adoc @@ -0,0 +1,3 @@ +*--manifest-path* _PATH_:: + Path to the `Cargo.toml` file. By default, Cargo searches in the current + directory or any parent directory for the `Cargo.toml` file. diff --git a/src/doc/man/options-message-format.adoc b/src/doc/man/options-message-format.adoc new file mode 100644 index 00000000000..6da9c26bd58 --- /dev/null +++ b/src/doc/man/options-message-format.adoc @@ -0,0 +1,6 @@ +*--message-format* _FMT_:: + The output format for diagnostic messages. Valid values: ++ +- `human` (default): Display in a human-readable text format. +- `json`: Emit JSON messages to stdout. +- `short`: Emit shorter, human-readable text messages. diff --git a/src/doc/man/options-new.adoc b/src/doc/man/options-new.adoc new file mode 100644 index 00000000000..6ede49e0208 --- /dev/null +++ b/src/doc/man/options-new.adoc @@ -0,0 +1,26 @@ +*--bin*:: + Create a package with a binary target (`src/main.rs`). + This is the default behavior. + +*--lib*:: + Create a package with a library target (`src/lib.rs`). + +*--edition* _EDITION_:: + Specify the Rust edition to use. Default is 2018. + Possible values: 2015, 2018 + +*--name* _NAME_:: + Set the package name. Defaults to the directory name. + +*--vcs* _VCS_:: + Initialize a new VCS repository for the given version control system (git, + hg, pijul, or fossil) or do not initialize any version control at all + (none). If not specified, defaults to `git` or the configuration value + `cargo-new.vcs`, or `none` if already inside a VCS repository. + +*--registry* _REGISTRY_:: + Alternative registry to use. This sets the `publish` field which will + restrict publishing only to the given registry name. ++ +This option is unstable and available only on the nightly channel and requires +the `-Z unstable-options` flag to enable. diff --git a/src/doc/man/options-package.adoc b/src/doc/man/options-package.adoc new file mode 100644 index 00000000000..c0cfbc35eef --- /dev/null +++ b/src/doc/man/options-package.adoc @@ -0,0 +1,7 @@ +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +*-p* _SPEC_:: +*--package* _SPEC_:: + The package to convert:lowercase[{actionverb}]. See man:cargo-pkgid[1] for + the SPEC format. diff --git a/src/doc/man/options-packages.adoc b/src/doc/man/options-packages.adoc new file mode 100644 index 00000000000..51ab9f0c370 --- /dev/null +++ b/src/doc/man/options-packages.adoc @@ -0,0 +1,18 @@ +By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (`--all` is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the `workspace.default-members` key in the root `Cargo.toml` +manifest. + +*-p* _SPEC_...:: +*--package* _SPEC_...:: + {actionverb} only the specified packages. See man:cargo-pkgid[1] for the + SPEC format. This flag may be specified multiple times. + +*--all*:: + {actionverb} all members in the workspace. + +*--exclude* _SPEC_...:: + Exclude the specified packages. Must be used in conjunction with the + `--all` flag. This flag may be specified multiple times. diff --git a/src/doc/man/options-profile.adoc b/src/doc/man/options-profile.adoc new file mode 100644 index 00000000000..3c5ad14c764 --- /dev/null +++ b/src/doc/man/options-profile.adoc @@ -0,0 +1,6 @@ +*--profile* _NAME_:: + Changes convert:lowercase[{actionverb}] behavior. Currently only `test` is + supported, which will convert:lowercase[{actionverb}] with the + `#[cfg(test)]` attribute enabled. This is useful to have it + convert:lowercase[{actionverb}] unit tests which are usually excluded via + the `cfg` attribute. This does not change the actual profile used. diff --git a/src/doc/man/options-registry.adoc b/src/doc/man/options-registry.adoc new file mode 100644 index 00000000000..79a035ea94f --- /dev/null +++ b/src/doc/man/options-registry.adoc @@ -0,0 +1,5 @@ +*--registry* _REGISTRY_:: + Alternative registry to use. ++ +This option is unstable and available only on the nightly channel and requires +the `-Z unstable-options` flag to enable. diff --git a/src/doc/man/options-release.adoc b/src/doc/man/options-release.adoc new file mode 100644 index 00000000000..211f9ecf2e6 --- /dev/null +++ b/src/doc/man/options-release.adoc @@ -0,0 +1,3 @@ +*--release*:: + {actionverb} artifacts in release mode, with optimizations. See the + <> section for details on how this affects profile selection. diff --git a/src/doc/man/options-target-dir.adoc b/src/doc/man/options-target-dir.adoc new file mode 100644 index 00000000000..f044bd71223 --- /dev/null +++ b/src/doc/man/options-target-dir.adoc @@ -0,0 +1,5 @@ +*--target-dir* _DIRECTORY_:: + Directory for all generated artifacts and intermediate files. May also be + specified with the `CARGO_TARGET_DIR` environment variable, or the + `build.target-dir` linkcargo:reference/config.html[config value]. Defaults + to `target` in the root of the workspace. diff --git a/src/doc/man/options-target-triple.adoc b/src/doc/man/options-target-triple.adoc new file mode 100644 index 00000000000..6ecb4401a3f --- /dev/null +++ b/src/doc/man/options-target-triple.adoc @@ -0,0 +1,22 @@ +*--target* _TRIPLE_:: + {actionverb} for the given architecture. The default is the host architecture. ++ +The general format of the triple is `---` where: ++ +- `arch` = The base CPU architecture, for example `x86_64`, `i686`, `arm`, + `thumb`, `mips`, etc. +- `sub` = The CPU sub-architecture, for example `arm` has `v7`, `v7s`, `v5te`, + etc. +- `vendor` = The vendor, for example `unknown`, `apple`, `pc`, `linux`, etc. +- `sys` = The system name, for example `linux`, `windows`, etc. `none` is + typically used for bare-metal without an OS. +- `abi` = The ABI, for example `gnu`, `android`, `eabi`, etc. + ++ +-- +Some parameters may be omitted. Run `rustc --print target-list` for a list of +supported targets. + +This may also be specified with the `build.target` +linkcargo:reference/config.html[config value]. +-- diff --git a/src/doc/man/options-targets-lib-bin.adoc b/src/doc/man/options-targets-lib-bin.adoc new file mode 100644 index 00000000000..8668ba84ba9 --- /dev/null +++ b/src/doc/man/options-targets-lib-bin.adoc @@ -0,0 +1,8 @@ +*--lib*:: + {actionverb} the package's library. + +*--bin* _NAME_...:: + {actionverb} the specified binary. This flag may be specified multiple times. + +*--bins*:: + {actionverb} all binary targets. diff --git a/src/doc/man/options-targets.adoc b/src/doc/man/options-targets.adoc new file mode 100644 index 00000000000..6b68fcd8742 --- /dev/null +++ b/src/doc/man/options-targets.adoc @@ -0,0 +1,33 @@ +Passing target selection flags will convert:lowercase[{actionverb}] only the +specified targets. + +include::options-targets-lib-bin.adoc[] + +*--example* _NAME_...:: + {actionverb} the specified example. This flag may be specified multiple times. + +*--examples*:: + {actionverb} all example targets. + +*--test* _NAME_...:: + {actionverb} the specified integration test. This flag may be specified multiple + times. + +*--tests*:: + {actionverb} all tests. This includes both unit tests for libraries and binaries + and integration tests. Targets may be disabled by setting `test = false` + in the manifest settings for the target. Targets (such as examples) may be + explicitly included by setting `test = true` in the target settings. + +*--bench* _NAME_...:: + {actionverb} the specified benchmark. This flag may be specified multiple times. + +*--benches*:: + {actionverb} all benchmarks. This includes both unit benchmarks for libraries and + binaries and bench targets. Targets may be disabled by setting `bench = + false` in the manifest settings for the target. Targets (such as examples) + may be explicitly included by setting `bench = true` in the target + settings. + +*--all-targets*:: + {actionverb} all targets. diff --git a/src/doc/man/options-test.adoc b/src/doc/man/options-test.adoc new file mode 100644 index 00000000000..0cdcb3d7efc --- /dev/null +++ b/src/doc/man/options-test.adoc @@ -0,0 +1,8 @@ +*--no-run*:: + Compile, but don't run {nouns}. + +*--no-fail-fast*:: + Run all {nouns} regardless of failure. Without this flag, Cargo will exit + after the first executable fails. The Rust test harness will run all + {nouns} within the executable to completion, this flag only applies to + the executable as a whole. diff --git a/src/doc/man/options-token.adoc b/src/doc/man/options-token.adoc new file mode 100644 index 00000000000..c303aa77656 --- /dev/null +++ b/src/doc/man/options-token.adoc @@ -0,0 +1,2 @@ +*--token* _TOKEN_:: + API token to use when authenticating. diff --git a/src/doc/man/section-environment.adoc b/src/doc/man/section-environment.adoc new file mode 100644 index 00000000000..5cc69e995a0 --- /dev/null +++ b/src/doc/man/section-environment.adoc @@ -0,0 +1,4 @@ +== ENVIRONMENT + +See linkcargo:reference/environment-variables.html[the reference] for +details on environment variables that Cargo reads. diff --git a/src/doc/man/section-exit-status.adoc b/src/doc/man/section-exit-status.adoc new file mode 100644 index 00000000000..427b3903c19 --- /dev/null +++ b/src/doc/man/section-exit-status.adoc @@ -0,0 +1,7 @@ +== Exit Status + +0:: + Cargo succeeded. + +101:: + Cargo failed to complete. diff --git a/src/doc/man/section-profiles.adoc b/src/doc/man/section-profiles.adoc new file mode 100644 index 00000000000..57b6598e9eb --- /dev/null +++ b/src/doc/man/section-profiles.adoc @@ -0,0 +1,24 @@ +== PROFILES + +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +linkcargo:reference/manifest.html#the-profile-sections[the reference] +for more details. + +Profile selection depends on the target and crate being built. By default the +`dev` or `test` profiles are used. If the `--release` flag is given, then the +`release` or `bench` profiles are used. + +|=== +|Target |Default Profile |`--release` Profile + +|lib, bin, example +|`dev` +|`release` + +|test, bench +|`test` +|`bench` +|=== + +Dependencies use the `dev`/`release` profiles. diff --git a/src/doc/src/SUMMARY.md b/src/doc/src/SUMMARY.md index 667d7cf4080..5b5293be877 100644 --- a/src/doc/src/SUMMARY.md +++ b/src/doc/src/SUMMARY.md @@ -29,5 +29,41 @@ * [External Tools](reference/external-tools.md) * [Unstable Features](reference/unstable.md) +* [Cargo Commands](commands/index.md) + * [Build Commands](commands/build-commands.md) + * [bench](commands/cargo-bench.md) + * [build](commands/cargo-build.md) + * [check](commands/cargo-check.md) + * [clean](commands/cargo-clean.md) + * [doc](commands/cargo-doc.md) + * [fetch](commands/cargo-fetch.md) + * [fix](commands/cargo-fix.md) + * [run](commands/cargo-run.md) + * [rustc](commands/cargo-rustc.md) + * [rustdoc](commands/cargo-rustdoc.md) + * [test](commands/cargo-test.md) + * [Manifest Commands](commands/manifest-commands.md) + * [generate-lockfile](commands/cargo-generate-lockfile.md) + * [locate-project](commands/cargo-locate-project.md) + * [metadata](commands/cargo-metadata.md) + * [pkgid](commands/cargo-pkgid.md) + * [update](commands/cargo-update.md) + * [verify-project](commands/cargo-verify-project.md) + * [Package Commands](commands/package-commands.md) + * [init](commands/cargo-init.md) + * [install](commands/cargo-install.md) + * [new](commands/cargo-new.md) + * [search](commands/cargo-search.md) + * [uninstall](commands/cargo-uninstall.md) + * [Publishing Commands](commands/publishing-commands.md) + * [login](commands/cargo-login.md) + * [owner](commands/cargo-owner.md) + * [package](commands/cargo-package.md) + * [publish](commands/cargo-publish.md) + * [yank](commands/cargo-yank.md) + * [General Commands](commands/general-commands.md) + * [help](commands/cargo-help.md) + * [version](commands/cargo-version.md) + * [FAQ](faq.md) * [Appendix: Glossary](appendix/glossary.md) diff --git a/src/doc/src/commands/build-commands.md b/src/doc/src/commands/build-commands.md new file mode 100644 index 00000000000..f472651811a --- /dev/null +++ b/src/doc/src/commands/build-commands.md @@ -0,0 +1 @@ +# Build Commands diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md new file mode 100644 index 00000000000..99a9861e342 --- /dev/null +++ b/src/doc/src/commands/cargo-bench.md @@ -0,0 +1,3 @@ +# cargo bench +{{#include command-common.html}} +{{#include generated/cargo-bench.html}} diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md new file mode 100644 index 00000000000..757f3711550 --- /dev/null +++ b/src/doc/src/commands/cargo-build.md @@ -0,0 +1,3 @@ +# cargo build +{{#include command-common.html}} +{{#include generated/cargo-build.html}} diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md new file mode 100644 index 00000000000..30009446161 --- /dev/null +++ b/src/doc/src/commands/cargo-check.md @@ -0,0 +1,3 @@ +# cargo check +{{#include command-common.html}} +{{#include generated/cargo-check.html}} diff --git a/src/doc/src/commands/cargo-clean.md b/src/doc/src/commands/cargo-clean.md new file mode 100644 index 00000000000..ec17e92a2cb --- /dev/null +++ b/src/doc/src/commands/cargo-clean.md @@ -0,0 +1,3 @@ +# cargo clean +{{#include command-common.html}} +{{#include generated/cargo-clean.html}} diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md new file mode 100644 index 00000000000..f6d2ef6a91e --- /dev/null +++ b/src/doc/src/commands/cargo-doc.md @@ -0,0 +1,3 @@ +# cargo doc +{{#include command-common.html}} +{{#include generated/cargo-doc.html}} diff --git a/src/doc/src/commands/cargo-fetch.md b/src/doc/src/commands/cargo-fetch.md new file mode 100644 index 00000000000..c7f52df33be --- /dev/null +++ b/src/doc/src/commands/cargo-fetch.md @@ -0,0 +1,3 @@ +# cargo fetch +{{#include command-common.html}} +{{#include generated/cargo-fetch.html}} diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md new file mode 100644 index 00000000000..ae669aa4825 --- /dev/null +++ b/src/doc/src/commands/cargo-fix.md @@ -0,0 +1,3 @@ +# cargo fix +{{#include command-common.html}} +{{#include generated/cargo-fix.html}} diff --git a/src/doc/src/commands/cargo-generate-lockfile.md b/src/doc/src/commands/cargo-generate-lockfile.md new file mode 100644 index 00000000000..b48bbfe09c2 --- /dev/null +++ b/src/doc/src/commands/cargo-generate-lockfile.md @@ -0,0 +1,3 @@ +# cargo generate-lockfile +{{#include command-common.html}} +{{#include generated/cargo-generate-lockfile.html}} diff --git a/src/doc/src/commands/cargo-help.md b/src/doc/src/commands/cargo-help.md new file mode 100644 index 00000000000..edae3750187 --- /dev/null +++ b/src/doc/src/commands/cargo-help.md @@ -0,0 +1,3 @@ +# cargo help +{{#include command-common.html}} +{{#include generated/cargo-help.html}} diff --git a/src/doc/src/commands/cargo-init.md b/src/doc/src/commands/cargo-init.md new file mode 100644 index 00000000000..8111ab33953 --- /dev/null +++ b/src/doc/src/commands/cargo-init.md @@ -0,0 +1,3 @@ +# cargo init +{{#include command-common.html}} +{{#include generated/cargo-init.html}} diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md new file mode 100644 index 00000000000..0a0dfafd5e7 --- /dev/null +++ b/src/doc/src/commands/cargo-install.md @@ -0,0 +1,3 @@ +# cargo install +{{#include command-common.html}} +{{#include generated/cargo-install.html}} diff --git a/src/doc/src/commands/cargo-locate-project.md b/src/doc/src/commands/cargo-locate-project.md new file mode 100644 index 00000000000..4928123e407 --- /dev/null +++ b/src/doc/src/commands/cargo-locate-project.md @@ -0,0 +1,3 @@ +# cargo locate-project +{{#include command-common.html}} +{{#include generated/cargo-locate-project.html}} diff --git a/src/doc/src/commands/cargo-login.md b/src/doc/src/commands/cargo-login.md new file mode 100644 index 00000000000..258a3c7495f --- /dev/null +++ b/src/doc/src/commands/cargo-login.md @@ -0,0 +1,3 @@ +# cargo login +{{#include command-common.html}} +{{#include generated/cargo-login.html}} diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md new file mode 100644 index 00000000000..d1354c5d689 --- /dev/null +++ b/src/doc/src/commands/cargo-metadata.md @@ -0,0 +1,3 @@ +# cargo metadata +{{#include command-common.html}} +{{#include generated/cargo-metadata.html}} diff --git a/src/doc/src/commands/cargo-new.md b/src/doc/src/commands/cargo-new.md new file mode 100644 index 00000000000..d1d1e17390f --- /dev/null +++ b/src/doc/src/commands/cargo-new.md @@ -0,0 +1,3 @@ +# cargo new +{{#include command-common.html}} +{{#include generated/cargo-new.html}} diff --git a/src/doc/src/commands/cargo-owner.md b/src/doc/src/commands/cargo-owner.md new file mode 100644 index 00000000000..3efd47ae452 --- /dev/null +++ b/src/doc/src/commands/cargo-owner.md @@ -0,0 +1,3 @@ +# cargo owner +{{#include command-common.html}} +{{#include generated/cargo-owner.html}} diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md new file mode 100644 index 00000000000..26ac7d710a0 --- /dev/null +++ b/src/doc/src/commands/cargo-package.md @@ -0,0 +1,3 @@ +# cargo package +{{#include command-common.html}} +{{#include generated/cargo-package.html}} diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md new file mode 100644 index 00000000000..97bce0f2cf8 --- /dev/null +++ b/src/doc/src/commands/cargo-pkgid.md @@ -0,0 +1,3 @@ +# cargo pkgid +{{#include command-common.html}} +{{#include generated/cargo-pkgid.html}} diff --git a/src/doc/src/commands/cargo-publish.md b/src/doc/src/commands/cargo-publish.md new file mode 100644 index 00000000000..074632a5bfc --- /dev/null +++ b/src/doc/src/commands/cargo-publish.md @@ -0,0 +1,3 @@ +# cargo publish +{{#include command-common.html}} +{{#include generated/cargo-publish.html}} diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md new file mode 100644 index 00000000000..032d0405916 --- /dev/null +++ b/src/doc/src/commands/cargo-run.md @@ -0,0 +1,3 @@ +# cargo run +{{#include command-common.html}} +{{#include generated/cargo-run.html}} diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md new file mode 100644 index 00000000000..75c1f32a131 --- /dev/null +++ b/src/doc/src/commands/cargo-rustc.md @@ -0,0 +1,3 @@ +# cargo rustc +{{#include command-common.html}} +{{#include generated/cargo-rustc.html}} diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md new file mode 100644 index 00000000000..97b6e1c9737 --- /dev/null +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -0,0 +1,3 @@ +# cargo rustdoc +{{#include command-common.html}} +{{#include generated/cargo-rustdoc.html}} diff --git a/src/doc/src/commands/cargo-search.md b/src/doc/src/commands/cargo-search.md new file mode 100644 index 00000000000..5c6de335698 --- /dev/null +++ b/src/doc/src/commands/cargo-search.md @@ -0,0 +1,3 @@ +# cargo search +{{#include command-common.html}} +{{#include generated/cargo-search.html}} diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md new file mode 100644 index 00000000000..59cff8c0ef6 --- /dev/null +++ b/src/doc/src/commands/cargo-test.md @@ -0,0 +1,3 @@ +# cargo test +{{#include command-common.html}} +{{#include generated/cargo-test.html}} diff --git a/src/doc/src/commands/cargo-uninstall.md b/src/doc/src/commands/cargo-uninstall.md new file mode 100644 index 00000000000..6d3ac9679e0 --- /dev/null +++ b/src/doc/src/commands/cargo-uninstall.md @@ -0,0 +1,3 @@ +# cargo uninstall +{{#include command-common.html}} +{{#include generated/cargo-uninstall.html}} diff --git a/src/doc/src/commands/cargo-update.md b/src/doc/src/commands/cargo-update.md new file mode 100644 index 00000000000..53e51c8c905 --- /dev/null +++ b/src/doc/src/commands/cargo-update.md @@ -0,0 +1,3 @@ +# cargo update +{{#include command-common.html}} +{{#include generated/cargo-update.html}} diff --git a/src/doc/src/commands/cargo-verify-project.md b/src/doc/src/commands/cargo-verify-project.md new file mode 100644 index 00000000000..baec04a1dbb --- /dev/null +++ b/src/doc/src/commands/cargo-verify-project.md @@ -0,0 +1,3 @@ +# cargo verify-project +{{#include command-common.html}} +{{#include generated/cargo-verify-project.html}} diff --git a/src/doc/src/commands/cargo-version.md b/src/doc/src/commands/cargo-version.md new file mode 100644 index 00000000000..8fd615efe5d --- /dev/null +++ b/src/doc/src/commands/cargo-version.md @@ -0,0 +1,3 @@ +# cargo version +{{#include command-common.html}} +{{#include generated/cargo-version.html}} diff --git a/src/doc/src/commands/cargo-yank.md b/src/doc/src/commands/cargo-yank.md new file mode 100644 index 00000000000..0a98069f200 --- /dev/null +++ b/src/doc/src/commands/cargo-yank.md @@ -0,0 +1,3 @@ +# cargo yank +{{#include command-common.html}} +{{#include generated/cargo-yank.html}} diff --git a/src/doc/src/commands/command-common.html b/src/doc/src/commands/command-common.html new file mode 100644 index 00000000000..93750600f27 --- /dev/null +++ b/src/doc/src/commands/command-common.html @@ -0,0 +1,18 @@ + diff --git a/src/doc/src/commands/general-commands.md b/src/doc/src/commands/general-commands.md new file mode 100644 index 00000000000..2fb4f7a9778 --- /dev/null +++ b/src/doc/src/commands/general-commands.md @@ -0,0 +1 @@ +# General Commands diff --git a/src/doc/src/commands/generated/cargo-bench.html b/src/doc/src/commands/generated/cargo-bench.html new file mode 100644 index 00000000000..6a4e86d434c --- /dev/null +++ b/src/doc/src/commands/generated/cargo-bench.html @@ -0,0 +1,487 @@ +

NAME

+
+

cargo-bench - Execute benchmarks of a package

+
+
+

SYNOPSIS

+
+
+

cargo bench [OPTIONS] [BENCHNAME] [-- BENCH-OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Compile and execute benchmarks.

+
+
+

The benchmark filtering argument BENCHNAME and all the arguments following +the two dashes (--) are passed to the benchmark binaries and thus to +libtest (rustc’s built in unit-test and micro-benchmarking framework). If +you’re passing arguments to both Cargo and the binary, the ones after -- go +to the binary, the ones before go to Cargo. For details about libtest’s +arguments see the output of cargo bench — --help. As an example, this will +run only the benchmark named foo (and skip other similarly named benchmarks +like foobar):

+
+
+
+
cargo bench -- foo --exact
+
+
+
+

Benchmarks are built with the --test option to rustc which creates an +executable with a main function that automatically runs all functions +annotated with the #[bench] attribute. The libtest harness may be disabled +by setting harness = false in the target manifest settings, in which case +your code will need to provide its own main function to handle running +benchmarks.

+
+
+
+
+

OPTIONS

+
+
+

Benchmark Options

+
+
+
--no-run
+
+

Compile, but don’t run benchmarks.

+
+
--no-fail-fast
+
+

Run all benchmarks regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all +benchmarks within the executable to completion, this flag only applies to +the executable as a whole.

+
+
+
+
+
+

Package Selection

+
+

By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (--all is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the workspace.default-members key in the root Cargo.toml +manifest.

+
+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Benchmark only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.

+
+
--all
+
+

Benchmark all members in the workspace.

+
+
--exclude SPEC…​
+
+

Exclude the specified packages. Must be used in conjunction with the +--all flag. This flag may be specified multiple times.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo bench will build the +following targets of the selected packages:

+
+
+
    +
  • +

    lib – used to link with binaries and benchmarks

    +
    • +
  • +

    bins (only if benchmark targets are built and required features are +available)

    +
    • +
  • +

    lib as a benchmark

    +
    • +
  • +

    bins as benchmarks

    +
    • +
  • +

    benchmark targets

    +
    • +
+
+
+

The default behavior can be changed by setting the bench flag for the target +in the manifest settings. Setting examples to bench = true will build and +run the example as a benchmark. Setting targets to bench = false will stop +them from being benchmarked by default. Target selection options that take a +target by name ignore the bench flag and will always benchmark the given +target.

+
+
+

Passing target selection flags will benchmark only the +specified targets.

+
+
+
+
--lib
+
+

Benchmark the package’s library.

+
+
--bin NAME…​
+
+

Benchmark the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Benchmark all binary targets.

+
+
--example NAME…​
+
+

Benchmark the specified example. This flag may be specified multiple times.

+
+
--examples
+
+

Benchmark all example targets.

+
+
--test NAME…​
+
+

Benchmark the specified integration test. This flag may be specified multiple +times.

+
+
--tests
+
+

Benchmark all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting test = false +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting test = true in the target settings.

+
+
--bench NAME…​
+
+

Benchmark the specified benchmark. This flag may be specified multiple times.

+
+
--benches
+
+

Benchmark all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting bench = +false in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting bench = true in the target +settings.

+
+
--all-targets
+
+

Benchmark all targets.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Benchmark for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+

By default the Rust test harness hides output from benchmark execution to keep +results readable. Benchmark output can be recovered (e.g. for debugging) by +passing --nocapture to the benchmark binaries:

+
+
+
+
cargo bench -- --nocapture
+
+
+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+

The --jobs argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread.

+
+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Benchmarks are always built with the bench profile. Binary and lib targets +are built separately as benchmarks with the bench profile. Library targets +are built with the release profiles when linked to binaries and benchmarks. +Dependencies use the release profile.

+
+
+

If you need a debug build of a benchmark, try building it with +cargo-build(1) which will use the test profile which is by default +unoptimized and includes debug information. You can then run the debug-enabled +benchmark manually.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Build and execute all the benchmarks of the current package:

    +
    +
    +
    cargo bench
    +
    +
    +
    2. +
  2. +

    Run only a specific benchmark within a specific benchmark target:

    +
    +
    +
    cargo bench --bench bench_name -- modname::some_benchmark
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-test(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-build.html b/src/doc/src/commands/generated/cargo-build.html new file mode 100644 index 00000000000..65c7d674d7d --- /dev/null +++ b/src/doc/src/commands/generated/cargo-build.html @@ -0,0 +1,448 @@ +

NAME

+
+

cargo-build - Compile the current package

+
+
+

SYNOPSIS

+
+
+

cargo build [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Compile local packages and all of their dependencies.

+
+
+
+
+

OPTIONS

+
+
+

Package Selection

+
+

By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (--all is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the workspace.default-members key in the root Cargo.toml +manifest.

+
+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Build only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.

+
+
--all
+
+

Build all members in the workspace.

+
+
--exclude SPEC…​
+
+

Exclude the specified packages. Must be used in conjunction with the +--all flag. This flag may be specified multiple times.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo build will build all +binary and library targets of the selected packages. Binaries are skipped if +they have required-features that are missing.

+
+
+

Passing target selection flags will build only the +specified targets.

+
+
+
+
--lib
+
+

Build the package’s library.

+
+
--bin NAME…​
+
+

Build the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Build all binary targets.

+
+
--example NAME…​
+
+

Build the specified example. This flag may be specified multiple times.

+
+
--examples
+
+

Build all example targets.

+
+
--test NAME…​
+
+

Build the specified integration test. This flag may be specified multiple +times.

+
+
--tests
+
+

Build all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting test = false +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting test = true in the target settings.

+
+
--bench NAME…​
+
+

Build the specified benchmark. This flag may be specified multiple times.

+
+
--benches
+
+

Build all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting bench = +false in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting bench = true in the target +settings.

+
+
--all-targets
+
+

Build all targets.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Build for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Build artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
--out-dir DIRECTORY
+
+

Copy final artifacts to this directory.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
--build-plan
+
+

Outputs a series of JSON messages to stdout that indicate the commands to +run the build.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Build the local package and all of its dependencies:

    +
    +
    +
    cargo build
    +
    +
    +
    2. +
  2. +

    Build with optimizations:

    +
    +
    +
    cargo build --release
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-rustc(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-check.html b/src/doc/src/commands/generated/cargo-check.html new file mode 100644 index 00000000000..0de23b3a992 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-check.html @@ -0,0 +1,443 @@ +

NAME

+
+

cargo-check - Check the current package

+
+
+

SYNOPSIS

+
+
+

cargo check [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Check a local package and all of its dependencies for errors. This will +essentially compile the packages without performing the final step of code +generation, which is faster than running cargo build. The compiler will save +metadata files to disk so that future runs will reuse them if the source has +not been modified.

+
+
+
+
+

OPTIONS

+
+
+

Package Selection

+
+

By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (--all is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the workspace.default-members key in the root Cargo.toml +manifest.

+
+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Check only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.

+
+
--all
+
+

Check all members in the workspace.

+
+
--exclude SPEC…​
+
+

Exclude the specified packages. Must be used in conjunction with the +--all flag. This flag may be specified multiple times.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo check will check all +binary and library targets of the selected packages. Binaries are skipped if +they have required-features that are missing.

+
+
+

Passing target selection flags will check only the +specified targets.

+
+
+
+
--lib
+
+

Check the package’s library.

+
+
--bin NAME…​
+
+

Check the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Check all binary targets.

+
+
--example NAME…​
+
+

Check the specified example. This flag may be specified multiple times.

+
+
--examples
+
+

Check all example targets.

+
+
--test NAME…​
+
+

Check the specified integration test. This flag may be specified multiple +times.

+
+
--tests
+
+

Check all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting test = false +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting test = true in the target settings.

+
+
--bench NAME…​
+
+

Check the specified benchmark. This flag may be specified multiple times.

+
+
--benches
+
+

Check all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting bench = +false in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting bench = true in the target +settings.

+
+
--all-targets
+
+

Check all targets.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Check for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Check artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
--profile NAME
+
+

Changes check behavior. Currently only test is +supported, which will check with the +#[cfg(test)] attribute enabled. This is useful to have it +check unit tests which are usually excluded via +the cfg attribute. This does not change the actual profile used.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Check the local package for errors:

    +
    +
    +
    cargo check
    +
    +
    +
    2. +
  2. +

    Check all targets, including unit tests:

    +
    +
    +
    cargo check --all-targets --profile=test
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-build(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-clean.html b/src/doc/src/commands/generated/cargo-clean.html new file mode 100644 index 00000000000..46ec74a0812 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-clean.html @@ -0,0 +1,254 @@ +

NAME

+
+

cargo-clean - Remove generated artifacts

+
+
+

SYNOPSIS

+
+
+

cargo clean [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Remove artifacts from the target directory that Cargo has generated in the +past.

+
+
+

With no options, cargo clean will delete the entire target directory.

+
+
+
+
+

OPTIONS

+
+
+

Package Selection

+
+

When no packages are selected, all packages and all dependencies in the +workspace are cleaned.

+
+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Clean only the specified packages. This flag may be specified +multiple times. See cargo-pkgid(1) for the SPEC format.

+
+
+
+
+
+

Clean Options

+
+
+
--doc
+
+

This option will cause cargo clean to remove only the doc directory in +the target directory.

+
+
--release
+
+

Clean all artifacts that were built with the release or bench +profiles.

+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
--target TRIPLE
+
+

Clean for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Remove the entire target directory:

    +
    +
    +
    cargo clean
    +
    +
    +
    2. +
  2. +

    Remove only the release artifacts:

    +
    +
    +
    cargo clean --release
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-build(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-doc.html b/src/doc/src/commands/generated/cargo-doc.html new file mode 100644 index 00000000000..0661ca39ceb --- /dev/null +++ b/src/doc/src/commands/generated/cargo-doc.html @@ -0,0 +1,410 @@ +

NAME

+
+

cargo-doc - Build a package's documentation

+
+
+

SYNOPSIS

+
+
+

cargo doc [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Build the documentation for the local package and all dependencies. The output +is placed in target/doc in rustdoc’s usual format.

+
+
+
+
+

OPTIONS

+
+
+

Documentation Options

+
+
+
--open
+
+

Open the docs in a browser after building them.

+
+
--no-deps
+
+

Do not build documentation for dependencies.

+
+
--document-private-items
+
+

Include non-public items in the documentation.

+
+
+
+
+
+

Package Selection

+
+

By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (--all is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the workspace.default-members key in the root Cargo.toml +manifest.

+
+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Document only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.

+
+
--all
+
+

Document all members in the workspace.

+
+
--exclude SPEC…​
+
+

Exclude the specified packages. Must be used in conjunction with the +--all flag. This flag may be specified multiple times.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo doc will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +required-features that are missing.

+
+
+

The default behavior can be changed by setting doc = false for the target in +the manifest settings. Using target selection options will ignore the doc +flag and will always document the given target.

+
+
+
+
--lib
+
+

Document the package’s library.

+
+
--bin NAME…​
+
+

Document the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Document all binary targets.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Document for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Document artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Build the local package documentation and its dependencies and output to +target/doc.

    +
    +
    +
    cargo doc
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-rustdoc(1), rustdoc(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-fetch.html b/src/doc/src/commands/generated/cargo-fetch.html new file mode 100644 index 00000000000..3f9ef393945 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-fetch.html @@ -0,0 +1,218 @@ +

NAME

+
+

cargo-fetch - Fetch dependencies of a package from the network

+
+
+

SYNOPSIS

+
+
+

cargo fetch [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

If a Cargo.lock file is available, this command will ensure that all of the +git dependencies and/or registry dependencies are downloaded and locally +available. Subsequent Cargo commands never touch the network after a cargo +fetch unless the lock file changes.

+
+
+

If the lock file is not available, then this command will generate the lock +file before fetching the dependencies.

+
+
+

If --target is not specified, then all target dependencies are fetched.

+
+
+
+
+

OPTIONS

+
+
+

Fetch options

+
+
+
--target TRIPLE
+
+

Fetch for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Fetch all dependencies:

    +
    +
    +
    cargo fetch
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-update(1), cargo-generate-lockfile(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-fix.html b/src/doc/src/commands/generated/cargo-fix.html new file mode 100644 index 00000000000..8ed4a5a0cc1 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-fix.html @@ -0,0 +1,522 @@ +

NAME

+
+

cargo-fix - Automatically fix lint warnings reported by rustc

+
+
+

SYNOPSIS

+
+
+

cargo fix [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

This Cargo subcommand will automatically take rustc’s suggestions from +diagnostics like warnings and apply them to your source code. This is intended +to help automate tasks that rustc itself already knows how to tell you to fix! +The cargo fix subcommand is also being developed for the Rust 2018 edition +to provide code the ability to easily opt-in to the new edition without having +to worry about any breakage.

+
+
+

Executing cargo fix will under the hood execute cargo-check(1). Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you’d like to prepare for the 2018 edition, you can do so by +executing:

+
+
+
+
cargo fix --edition
+
+
+
+

which behaves the same as cargo check --all-targets. Similarly if you’d like +to fix code for different platforms you can do:

+
+
+
+
cargo fix --edition --target x86_64-pc-windows-gnu
+
+
+
+

or if your crate has optional features:

+
+
+
+
cargo fix --edition --no-default-features --features foo
+
+
+
+

If you encounter any problems with cargo fix or otherwise have any questions +or feature requests please don’t hesitate to file an issue at +https://github.com/rust-lang/cargo

+
+
+
+
+

OPTIONS

+
+
+

Fix options

+
+
+
--broken-code
+
+

Fix code even if it already has compiler errors. This is useful if cargo +fix fails to apply the changes. It will apply the changes and leave the +broken code in the working directory for you to inspect and manually fix.

+
+
--edition
+
+

Apply changes that will update the code to the latest edition. This will +not update the edition in the Cargo.toml manifest, which must be updated +manually.

+
+
--edition-idioms
+
+

Apply suggestions that will update code to the preferred style for the +current edition.

+
+
--allow-no-vcs
+
+

Fix code even if a VCS was not detected.

+
+
--allow-dirty
+
+

Fix code even if the working directory has changes.

+
+
--allow-staged
+
+

Fix code even if the working directory has staged changes.

+
+
+
+
+
+

Package Selection

+
+

By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (--all is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the workspace.default-members key in the root Cargo.toml +manifest.

+
+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Fix only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.

+
+
--all
+
+

Fix all members in the workspace.

+
+
--exclude SPEC…​
+
+

Exclude the specified packages. Must be used in conjunction with the +--all flag. This flag may be specified multiple times.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo fix will fix all targets +(--all-targets implied). Binaries are skipped if they have +required-features that are missing.

+
+
+

Passing target selection flags will fix only the +specified targets.

+
+
+
+
--lib
+
+

Fix the package’s library.

+
+
--bin NAME…​
+
+

Fix the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Fix all binary targets.

+
+
--example NAME…​
+
+

Fix the specified example. This flag may be specified multiple times.

+
+
--examples
+
+

Fix all example targets.

+
+
--test NAME…​
+
+

Fix the specified integration test. This flag may be specified multiple +times.

+
+
--tests
+
+

Fix all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting test = false +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting test = true in the target settings.

+
+
--bench NAME…​
+
+

Fix the specified benchmark. This flag may be specified multiple times.

+
+
--benches
+
+

Fix all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting bench = +false in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting bench = true in the target +settings.

+
+
--all-targets
+
+

Fix all targets.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Fix for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Fix artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
--profile NAME
+
+

Changes fix behavior. Currently only test is +supported, which will fix with the +#[cfg(test)] attribute enabled. This is useful to have it +fix unit tests which are usually excluded via +the cfg attribute. This does not change the actual profile used.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Apply compiler suggestions to the local package:

    +
    +
    +
    cargo fix
    +
    +
    +
    2. +
  2. +

    Convert a 2015 edition to 2018:

    +
    +
    +
    cargo fix --edition
    +
    +
    +
    3. +
  3. +

    Apply suggested idioms for the current edition:

    +
    +
    +
    cargo fix --edition-idioms
    +
    +
    +
    4. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-check(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-generate-lockfile.html b/src/doc/src/commands/generated/cargo-generate-lockfile.html new file mode 100644 index 00000000000..b562cc91c27 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-generate-lockfile.html @@ -0,0 +1,166 @@ +

NAME

+
+

cargo-generate-lockfile - Generate the lockfile for a package

+
+
+

SYNOPSIS

+
+
+

cargo generate-lockfile [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will create the Cargo.lock lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt if there are any +manifest changes or dependency updates.

+
+
+

See also cargo-update(1) which is also capable of creating a Cargo.lock +lockfile and has more options for controlling update behavior.

+
+
+
+
+

OPTIONS

+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Create or update the lockfile for the current package or workspace:

    +
    +
    +
    cargo generate-lockfile
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-update(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-help.html b/src/doc/src/commands/generated/cargo-help.html new file mode 100644 index 00000000000..58503c7d15e --- /dev/null +++ b/src/doc/src/commands/generated/cargo-help.html @@ -0,0 +1,53 @@ +

NAME

+
+

cargo-help - Get help for a Cargo command

+
+
+

SYNOPSIS

+
+
+

cargo help [SUBCOMMAND]

+
+
+
+
+

DESCRIPTION

+
+
+

Prints a help message for the given command.

+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Get help for a command:

    +
    +
    +
    cargo help build
    +
    +
    +
    2. +
  2. +

    Help is also available with the --help flag:

    +
    +
    +
    cargo build --help
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-init.html b/src/doc/src/commands/generated/cargo-init.html new file mode 100644 index 00000000000..b6d04b81874 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-init.html @@ -0,0 +1,252 @@ +

NAME

+
+

cargo-init - Create a new Cargo package in an existing directory

+
+
+

SYNOPSIS

+
+
+

cargo init [OPTIONS] [PATH]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory.

+
+
+

If there are typically-named Rust source files already in the directory, those +will be used. If not, then a sample src/main.rs file will be created, or +src/lib.rs if --lib is passed.

+
+
+

If the directory is not already in a VCS repository, then a new repository +is created (see --vcs below).

+
+
+

The "authors" field in the manifest is determined from the environment or +configuration settings. A name is required and is determined from (first match +wins):

+
+
+
    +
  • +

    cargo-new.name Cargo config value

    +
    • +
  • +

    CARGO_NAME environment variable

    +
    • +
  • +

    GIT_AUTHOR_NAME environment variable

    +
    • +
  • +

    GIT_COMMITTER_NAME environment variable

    +
    • +
  • +

    user.name git configuration value

    +
    • +
  • +

    USER environment variable

    +
    • +
  • +

    USERNAME environment variable

    +
    • +
  • +

    NAME environment variable

    +
    • +
+
+
+

The email address is optional and is determined from:

+
+
+
    +
  • +

    cargo-new.email Cargo config value

    +
    • +
  • +

    CARGO_EMAIL environment variable

    +
    • +
  • +

    GIT_AUTHOR_EMAIL environment variable

    +
    • +
  • +

    GIT_COMMITTER_EMAIL environment variable

    +
    • +
  • +

    user.email git configuration value

    +
    • +
  • +

    EMAIL environment variable

    +
    • +
+
+
+

See the reference for more information about +configuration files.

+
+
+

See cargo-new(1) for a similar command which will create a new package in +a new directory.

+
+
+
+
+

OPTIONS

+
+
+

Init Options

+
+
+
--bin
+
+

Create a package with a binary target (src/main.rs). +This is the default behavior.

+
+
--lib
+
+

Create a package with a library target (src/lib.rs).

+
+
--edition EDITION
+
+

Specify the Rust edition to use. Default is 2018. +Possible values: 2015, 2018

+
+
--name NAME
+
+

Set the package name. Defaults to the directory name.

+
+
--vcs VCS
+
+

Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to git or the configuration value +cargo-new.vcs, or none if already inside a VCS repository.

+
+
--registry REGISTRY
+
+

Alternative registry to use. This sets the publish field which will +restrict publishing only to the given registry name.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Create a binary Cargo package in the current directory:

    +
    +
    +
    cargo init
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-new(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-install.html b/src/doc/src/commands/generated/cargo-install.html new file mode 100644 index 00000000000..f98ee481ece --- /dev/null +++ b/src/doc/src/commands/generated/cargo-install.html @@ -0,0 +1,354 @@ +

NAME

+
+

cargo-install - Build and install a Rust binary

+
+
+

SYNOPSIS

+
+
+

cargo install [OPTIONS] CRATE…​
+cargo install [OPTIONS] --path PATH
+cargo install [OPTIONS] --git URL [CRATE…​]
+cargo install [OPTIONS] --list

+
+
+
+
+

DESCRIPTION

+
+
+

This command manages Cargo’s local set of installed binary crates. Only packages +which have [[bin]] targets can be installed, and all binaries are installed into +the installation root’s bin folder.

+
+
+

The installation root is determined, in order of precedence:

+
+
+
    +
  • +

    --root option

    +
    • +
  • +

    CARGO_INSTALL_ROOT environment variable

    +
    • +
  • +

    install.root Cargo config value

    +
    • +
  • +

    CARGO_HOME environment variable

    +
    • +
  • +

    $HOME/.cargo

    +
    • +
+
+
+

There are multiple sources from which a crate can be installed. The default +location is crates.io but the --git and --path flags can change this +source. If the source contains more than one package (such as crates.io or a +git repository with multiple crates) the CRATE argument is required to +indicate which crate should be installed.

+
+
+

Crates from crates.io can optionally specify the version they wish to install +via the --version flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the --bin argument can selectively install only +one of them, and if you’d rather install examples the --example argument can +be used as well.

+
+
+

If the source is crates.io or --git then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the CARGO_TARGET_DIR environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems.

+
+
+
+
+

OPTIONS

+
+
+

Install Options

+
+
+
--vers VERSION
+
--version VERSION
+
+

Specify a version to install from crates.io.

+
+
--git URL
+
+

Git URL to install the specified crate from.

+
+
--branch BRANCH
+
+

Branch to use when installing from git.

+
+
--tag TAG
+
+

Tag to use when installing from git.

+
+
--rev SHA
+
+

Specific commit to use when installing from git.

+
+
--path PATH
+
+

Filesystem path to local crate to install.

+
+
--list
+
+

List all installed packages and their versions.

+
+
-f
+
--force
+
+

Force overwriting existing crates or binaries. This can be used to +reinstall or upgrade a crate.

+
+
--bin NAME…​
+
+

Install only the specified binary.

+
+
--bins
+
+

Install all binaries.

+
+
--example NAME…​
+
+

Install only the specified example.

+
+
--examples
+
+

Install all examples.

+
+
--root DIR
+
+

Directory to install packages into.

+
+
--registry REGISTRY
+
+

Alternative registry to use.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Install for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--debug
+
+

Build in debug mode instead of release mode.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Install a package from crates.io:

    +
    +
    +
    cargo install ripgrep
    +
    +
    +
    2. +
  2. +

    Reinstall or upgrade a package:

    +
    +
    +
    cargo install ripgrep --force
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-locate-project.html b/src/doc/src/commands/generated/cargo-locate-project.html new file mode 100644 index 00000000000..0b13f76cf1e --- /dev/null +++ b/src/doc/src/commands/generated/cargo-locate-project.html @@ -0,0 +1,152 @@ +

NAME

+
+

cargo-locate-project - Print a JSON representation of a Cargo.toml file's location

+
+
+

SYNOPSIS

+
+
+

cargo locate-project [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will print a JSON object to stdout with the full path to the +Cargo.toml manifest.

+
+
+

See also cargo-metadata(1) which is capable of returning the path to a +workspace root.

+
+
+
+
+

OPTIONS

+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Display the path to the manifest based on the current directory:

    +
    +
    +
    cargo locate-project
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-metadata(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-login.html b/src/doc/src/commands/generated/cargo-login.html new file mode 100644 index 00000000000..3702e0b86f7 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-login.html @@ -0,0 +1,167 @@ +

NAME

+
+

cargo-login - Save an API token from the registry locally

+
+
+

SYNOPSIS

+
+
+

cargo login [OPTIONS] [TOKEN]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will save the API token to disk so that commands that require +authentication (such as cargo-publish(1)) will be automatically +authenticated. The token is saved in $CARGO_HOME/credentials. CARGO_HOME +defaults to .cargo in your home directory.

+
+
+

If the TOKEN argument is not specified, it will be read from stdin.

+
+
+

The API token for crates.io may be retrieved from https://crates.io/me.

+
+
+

Take care to keep the token secret, it should not be shared with anyone else.

+
+
+
+
+

OPTIONS

+
+
+

Login Options

+
+
+
--host HOST
+
+

Host to set the token for. This option does not affect the behavior of the +login command, and only affects the message displayed.

+
+
--registry REGISTRY
+
+

Alternative registry to use.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Save the API token to disk:

    +
    +
    +
    cargo login
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-publish(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-metadata.html b/src/doc/src/commands/generated/cargo-metadata.html new file mode 100644 index 00000000000..d9ed8aea61b --- /dev/null +++ b/src/doc/src/commands/generated/cargo-metadata.html @@ -0,0 +1,427 @@ +

NAME

+
+

cargo-metadata - Machine-readable metadata about the current package

+
+
+

SYNOPSIS

+
+
+

cargo metadata [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Output the resolved dependencies of a package, the concrete used versions +including overrides, in JSON to stdout.

+
+
+

It is recommended to include the --format-version flag to future-proof +your code to ensure the output is in the format you are expecting.

+
+
+

See the cargo_metadata crate +for a Rust API for reading the metadata.

+
+
+
+
+

OUTPUT FORMAT

+
+
+

The output has the following format:

+
+
+
+
{
+    /* Array of all packages in the workspace.
+       It also includes all feature-enabled dependencies unless --no-deps is used.
+    */
+    "packages": [
+        {
+            /* The name of the package. */
+            "name": "my-package",
+            /* The version of the package. */
+            "version": "0.1.0",
+            /* The Package ID, a unique identifier for referring to the package. */
+            "id": "my-package 0.1.0 (path+file:///path/to/my-package)",
+            /* The license value from the manifest, or null. */
+            "license": "MIT/Apache-2.0",
+            /* The license-file value from the manifest, or null. */
+            "license_file": "LICENSE",
+            /* The description value from the manifest, or null. */
+            "description": "Package description.",
+            /* The source ID of the package. This represents where
+               a package is retrieved from.
+               This is null for path dependencies and workspace members.
+               For other dependencies, it is a string with the format:
+               - "registry+URL" for registry-based dependencies.
+                 Example: "registry+https://github.com/rust-lang/crates.io-index"
+               - "git+URL" for git-based dependencies.
+                 Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
+            */
+            "source": null,
+            /* Array of dependencies declared in the package's manifest. */
+            "dependencies": [
+                {
+                    /* The name of the dependency. */
+                    "name": "bitflags",
+                    /* The source ID of the dependency. */
+                    "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)"
+                }
+            ],
+            /* 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"]
+                }
+            ],
+            /* 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
+                    }
+                }
+            },
+            /* 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"
+            ],
+            /* Array of keywords from the manifest. */
+            "keywords": [
+                "cli"
+            ],
+            /* The readme value from the manifest or null if not specified. */
+            "readme": "README.md",
+            /* The repository value from the manifest or null if not specified. */
+            "repository": "https://github.com/rust-lang/cargo",
+            /* The default edition of the package.
+               Note that individual targets may have different editions.
+            */
+            "edition": "2018"
+        }
+    ],
+    /* 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, with the concrete versions and features
+       selected. The set depends on the enabled features.
+       This is null if --no-deps is specified.
+    */
+    "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.
+                           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 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"
+}
+
+
+
+
+
+

OPTIONS

+
+
+

Output Options

+
+
+
--no-deps
+
+

Output information only about the workspace members and don’t fetch +dependencies.

+
+
--format-version VERSION
+
+

Specify the version of the output format to use. Currently 1 is the only +possible value.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Output JSON about the current package:

    +
    +
    +
    cargo metadata --format-version=1
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-new.html b/src/doc/src/commands/generated/cargo-new.html new file mode 100644 index 00000000000..270aa3a826a --- /dev/null +++ b/src/doc/src/commands/generated/cargo-new.html @@ -0,0 +1,245 @@ +

NAME

+
+

cargo-new - Create a new Cargo package

+
+
+

SYNOPSIS

+
+
+

cargo new [OPTIONS] PATH

+
+
+
+
+

DESCRIPTION

+
+
+

This command will create a new Cargo package in the given directory. This +includes a simple template with a Cargo.toml manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see --vcs below).

+
+
+

The "authors" field in the manifest is determined from the environment or +configuration settings. A name is required and is determined from (first match +wins):

+
+
+
    +
  • +

    cargo-new.name Cargo config value

    +
    • +
  • +

    CARGO_NAME environment variable

    +
    • +
  • +

    GIT_AUTHOR_NAME environment variable

    +
    • +
  • +

    GIT_COMMITTER_NAME environment variable

    +
    • +
  • +

    user.name git configuration value

    +
    • +
  • +

    USER environment variable

    +
    • +
  • +

    USERNAME environment variable

    +
    • +
  • +

    NAME environment variable

    +
    • +
+
+
+

The email address is optional and is determined from:

+
+
+
    +
  • +

    cargo-new.email Cargo config value

    +
    • +
  • +

    CARGO_EMAIL environment variable

    +
    • +
  • +

    GIT_AUTHOR_EMAIL environment variable

    +
    • +
  • +

    GIT_COMMITTER_EMAIL environment variable

    +
    • +
  • +

    user.email git configuration value

    +
    • +
  • +

    EMAIL environment variable

    +
    • +
+
+
+

See the reference for more information about +configuration files.

+
+
+

See cargo-init(1) for a similar command which will create a new manifest +in an existing directory.

+
+
+
+
+

OPTIONS

+
+
+

New Options

+
+
+
--bin
+
+

Create a package with a binary target (src/main.rs). +This is the default behavior.

+
+
--lib
+
+

Create a package with a library target (src/lib.rs).

+
+
--edition EDITION
+
+

Specify the Rust edition to use. Default is 2018. +Possible values: 2015, 2018

+
+
--name NAME
+
+

Set the package name. Defaults to the directory name.

+
+
--vcs VCS
+
+

Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to git or the configuration value +cargo-new.vcs, or none if already inside a VCS repository.

+
+
--registry REGISTRY
+
+

Alternative registry to use. This sets the publish field which will +restrict publishing only to the given registry name.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Create a binary Cargo package in the given directory:

    +
    +
    +
    cargo new foo
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-init(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-owner.html b/src/doc/src/commands/generated/cargo-owner.html new file mode 100644 index 00000000000..60cb2e3b8e8 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-owner.html @@ -0,0 +1,205 @@ +

NAME

+
+

cargo-owner - Manage the owners of a crate on the registry

+
+
+

SYNOPSIS

+
+
+

cargo owner [OPTIONS] --add LOGIN [CRATE]
+cargo owner [OPTIONS] --remove LOGIN [CRATE]
+cargo owner [OPTIONS] --list [CRATE]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will modify the owners for a crate on the registry. Owners of a +crate can upload new versions and yank old versions. Non-team owners can also +modify the set of owners, so take care!

+
+
+

This command requires you to be authenticated with either the --token option +or using cargo-login(1).

+
+
+

If the crate name is not specified, it will use the package name from the +current directory.

+
+
+

See the reference for more +information about owners and publishing.

+
+
+
+
+

OPTIONS

+
+
+

Owner Options

+
+
+
-a
+
--add LOGIN…​
+
+

Add the given user or team as an owner.

+
+
-r
+
--remove LOGIN…​
+
+

Remove the given user or team as an owner.

+
+
-l
+
--list
+
+

List owners of a crate.

+
+
--token TOKEN
+
+

API token to use when authenticating.

+
+
--index INDEX
+
+

The URL of the registry index to use.

+
+
--registry REGISTRY
+
+

Alternative registry to use.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    List owners of a package:

    +
    +
    +
    cargo owner --list foo
    +
    +
    +
    2. +
  2. +

    Add an owner to a package:

    +
    +
    +
    cargo owner --add username foo
    +
    +
    +
    3. +
  3. +

    Remove an owner from a package:

    +
    +
    +
    cargo owner --remove username foo
    +
    +
    +
    4. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-login(1), cargo-publish(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-package.html b/src/doc/src/commands/generated/cargo-package.html new file mode 100644 index 00000000000..96b66428bed --- /dev/null +++ b/src/doc/src/commands/generated/cargo-package.html @@ -0,0 +1,301 @@ +

NAME

+
+

cargo-package - Assemble the local package into a distributable tarball

+
+
+

SYNOPSIS

+
+
+

cargo package [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will create a distributable, compressed .crate file with the +source code of the package in the current directory. The resulting file will +be stored in the target/package directory. This performs the following +steps:

+
+
+
    +
  1. +

    Load and check the current workspace, performing some basic checks.

    +
    +
      +
    • +

      Path dependencies are not allowed unless they have a version key. Cargo +will ignore the path key for dependencies in published packages.

      +
      • +
    +
    +
    2. +
  2. +

    Create the compressed .crate file.

    +
    +
      +
    • +

      The original Cargo.toml file is rewritten and normalized.

      +
      • +
    • +

      A .cargo_vcs_info.json file is included that contains information +about the current VCS checkout hash if available (not included with +--allow-dirty).

      +
      • +
    +
    +
    3. +
  3. +

    Extract the .crate file and build it to verify it can build.

    +
    4. +
  4. +

    Check that build scripts did not modify any source files.

    +
    5. +
+
+
+

The list of files included can be controlled with the include and exclude +fields in the manifest.

+
+
+

See the reference for more details about +packaging and publishing.

+
+
+
+
+

OPTIONS

+
+
+

Package Options

+
+
+
-l
+
--list
+
+

Print files included in a package without making one.

+
+
--no-verify
+
+

Don’t verify the contents by building them.

+
+
--no-metadata
+
+

Ignore warnings about a lack of human-usable metadata (such as the +description or the license).

+
+
--allow-dirty
+
+

Allow working directories with uncommitted VCS changes to be packaged.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Package for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Create a compressed .crate file of the current package:

    +
    +
    +
    cargo package
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-publish(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-pkgid.html b/src/doc/src/commands/generated/cargo-pkgid.html new file mode 100644 index 00000000000..0d365edda49 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-pkgid.html @@ -0,0 +1,241 @@ +

NAME

+
+

cargo-pkgid - Print a fully qualified package specification

+
+
+

SYNOPSIS

+
+
+

cargo pkgid [OPTIONS] [SPEC]

+
+
+
+
+

DESCRIPTION

+
+
+

Given a SPEC argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if SPEC is ambiguous as to which package it refers to in +the dependency graph. If no SPEC is given, then the specifier for the local +package is printed.

+
+
+

This command requires that a lockfile is available and dependencies have been +fetched.

+
+
+

A package specifier consists of a name, version, and source URL. You are +allowed to use partial specifiers to succinctly match a specific package as +long as it matches only one package. The format of a SPEC can be one of the +following:

+
+ + ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1. SPEC Query Format
SPEC StructureExample SPEC

NAME

bitflags

NAME:VERSION

bitflags:1.0.4

URL

https://github.com/rust-lang/cargo

URL#VERSION

https://github.com/rust-lang/cargo#0.33.0

URL#NAME

https://github.com/rust-lang/crates.io-index#bitflags

URL#NAME:VERSION

https://github.com/rust-lang/cargo#crates-io:0.21.0

+
+
+
+

OPTIONS

+
+
+

Package Selection

+
+
+
-p SPEC
+
--package SPEC
+
+

Get the package ID for the given package instead of the current package.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Retrieve package specification for foo package:

    +
    +
    +
    cargo pkgid foo
    +
    +
    +
    2. +
  2. +

    Retrieve package specification for version 1.0.0 of foo:

    +
    +
    +
    cargo pkgid foo:1.0.0
    +
    +
    +
    3. +
  3. +

    Retrieve package specification for foo from crates.io:

    +
    +
    +
    cargo pkgid https://github.com/rust-lang/crates.io-index#foo
    +
    +
    +
    4. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-generate-lockfile(1), cargo-metadata(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-publish.html b/src/doc/src/commands/generated/cargo-publish.html new file mode 100644 index 00000000000..d68f66a6d8e --- /dev/null +++ b/src/doc/src/commands/generated/cargo-publish.html @@ -0,0 +1,300 @@ +

NAME

+
+

cargo-publish - Upload a package to the registry

+
+
+

SYNOPSIS

+
+
+

cargo package [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will create a distributable, compressed .crate file with the +source code of the package in the current directory and upload it to a +registry. The default registry is https://crates.io. This performs the +following steps:

+
+
+
    +
  1. +

    Performs a few checks, including:

    +
    +
      +
    • +

      No [patch] sections are allowed in the manifest.

      +
      • +
    • +

      Checks the package.publish key in the manifest for restrictions on which +registries you are allowed to publish to.

      +
      • +
    +
    +
    2. +
  2. +

    Create a .crate file by following the steps in cargo-package(1).

    +
    3. +
  3. +

    Upload the crate to the registry. Note that the server will perform +additional checks on the crate.

    +
    4. +
+
+
+

This command requires you to be authenticated with either the --token option +or using cargo-login(1).

+
+
+

See the reference for more details about +packaging and publishing.

+
+
+
+
+

OPTIONS

+
+
+

Publish Options

+
+
+
--dry-run
+
+

Perform all checks without uploading.

+
+
--token TOKEN
+
+

API token to use when authenticating.

+
+
--no-verify
+
+

Don’t verify the contents by building them.

+
+
--allow-dirty
+
+

Allow working directories with uncommitted VCS changes to be packaged.

+
+
--index INDEX
+
+

The URL of the registry index to use.

+
+
--registry REGISTRY
+
+

Alternative registry to use.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Publish for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Publish the current package:

    +
    +
    +
    cargo publish
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-package(1), cargo-login(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-run.html b/src/doc/src/commands/generated/cargo-run.html new file mode 100644 index 00000000000..5ea1259b6ac --- /dev/null +++ b/src/doc/src/commands/generated/cargo-run.html @@ -0,0 +1,379 @@ +

NAME

+
+

cargo-run - Run the current package

+
+
+

SYNOPSIS

+
+
+

cargo run [OPTIONS] [-- ARGS]

+
+
+
+
+

DESCRIPTION

+
+
+

Build the the main binary of the local package (src/main.rs) and run it.

+
+
+

All the arguments following the two dashes (--) are passed to the binary to +run. If you’re passing arguments to both Cargo and the binary, the ones after +-- go to the binary, the ones before go to Cargo.

+
+
+
+
+

OPTIONS

+
+
+

Package Selection

+
+

By default, the package in the current working directory is selected. The -p +flag can be used to choose a different package in a workspace.

+
+
+
+
-p SPEC
+
--package SPEC
+
+

The package to run. See cargo-pkgid(1) for +the SPEC format.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo run will run the binary +target. If there are multiple binary targets, you must pass a target flag to +choose one.

+
+
+
+
--bin NAME
+
+

Run the specified binary.

+
+
--example NAME
+
+

Run the specified example.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Run for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Run artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Build the local package and run its main target:

    +
    +
    +
    cargo run
    +
    +
    +
    2. +
  2. +

    Run an example with extra arguments:

    +
    +
    +
    cargo run --example exname -- --exoption exarg1 exarg2
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-build(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-rustc.html b/src/doc/src/commands/generated/cargo-rustc.html new file mode 100644 index 00000000000..d46f8255e22 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-rustc.html @@ -0,0 +1,436 @@ +

NAME

+
+

cargo-rustc - Compile the current package, and pass extra options to the compiler

+
+
+

SYNOPSIS

+
+
+

cargo rustc [OPTIONS] [-- ARGS]

+
+
+
+
+

DESCRIPTION

+
+
+

The specified target for the current package (or package specified by -p if +provided) will be compiled along with all of its dependencies. The specified +ARGS will all be passed to the final compiler invocation, not any of the +dependencies. Note that the compiler will still unconditionally receive +arguments such as -L, --extern, and --crate-type, and the specified +ARGS will simply be added to the compiler invocation.

+
+
+

See https://doc.rust-lang.org/rustc/index.html for documentation on rustc +flags.

+
+
+

This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of --lib, --bin, etc, must be used to select which +target is compiled. +To pass flags to all compiler processes spawned by Cargo, use the RUSTFLAGS +environment variable or the build.rustflags +config value.

+
+
+
+
+

OPTIONS

+
+
+

Package Selection

+
+

By default, the package in the current working directory is selected. The -p +flag can be used to choose a different package in a workspace.

+
+
+
+
-p SPEC
+
--package SPEC
+
+

The package to build. See cargo-pkgid(1) for +the SPEC format.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo rustc will build all +binary and library targets of the selected package.

+
+
+

Passing target selection flags will build only the +specified targets.

+
+
+
+
--lib
+
+

Build the package’s library.

+
+
--bin NAME…​
+
+

Build the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Build all binary targets.

+
+
--example NAME…​
+
+

Build the specified example. This flag may be specified multiple times.

+
+
--examples
+
+

Build all example targets.

+
+
--test NAME…​
+
+

Build the specified integration test. This flag may be specified multiple +times.

+
+
--tests
+
+

Build all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting test = false +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting test = true in the target settings.

+
+
--bench NAME…​
+
+

Build the specified benchmark. This flag may be specified multiple times.

+
+
--benches
+
+

Build all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting bench = +false in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting bench = true in the target +settings.

+
+
--all-targets
+
+

Build all targets.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Build for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Build artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Check if your package (not including dependencies) uses unsafe code:

    +
    +
    +
    cargo rustc --lib -- -D unsafe-code
    +
    +
    +
    2. +
  2. +

    Try an experimental flag on the nightly compiler, such as this which prints +the size of every type:

    +
    +
    +
    cargo rustc --lib -- -Z print-type-sizes
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-build(1), rustc(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-rustdoc.html b/src/doc/src/commands/generated/cargo-rustdoc.html new file mode 100644 index 00000000000..d9c9937a1ac --- /dev/null +++ b/src/doc/src/commands/generated/cargo-rustdoc.html @@ -0,0 +1,440 @@ +

NAME

+
+

cargo-rustdoc - Build a package's documentation, using specified custom flags

+
+
+

SYNOPSIS

+
+
+

cargo rustdoc [OPTIONS] [-- ARGS]

+
+
+
+
+

DESCRIPTION

+
+
+

The specified target for the current package (or package specified by -p if +provided) will be documented with the specified ARGS being passed to the +final rustdoc invocation. Dependencies will not be documented as part of this +command. Note that rustdoc will still unconditionally receive arguments such +as -L, --extern, and --crate-type, and the specified ARGS will simply +be added to the rustdoc invocation.

+
+
+

See https://doc.rust-lang.org/rustdoc/index.html for documentation on rustdoc +flags.

+
+
+

This command requires that only one target is being compiled when additional +arguments are provided. If more than one target is available for the current +package the filters of --lib, --bin, etc, must be used to select which +target is compiled. +To pass flags to all rustdoc processes spawned by Cargo, use the +RUSTDOCFLAGS environment variable or the build.rustdocflags configuration +option.

+
+
+
+
+

OPTIONS

+
+
+

Documentation Options

+
+
+
--open
+
+

Open the docs in a browser after building them.

+
+
+
+
+
+

Package Selection

+
+

By default, the package in the current working directory is selected. The -p +flag can be used to choose a different package in a workspace.

+
+
+
+
-p SPEC
+
--package SPEC
+
+

The package to document. See cargo-pkgid(1) for +the SPEC format.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo rustdoc will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +required-features that are missing.

+
+
+

Passing target selection flags will document only the +specified targets.

+
+
+
+
--lib
+
+

Document the package’s library.

+
+
--bin NAME…​
+
+

Document the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Document all binary targets.

+
+
--example NAME…​
+
+

Document the specified example. This flag may be specified multiple times.

+
+
--examples
+
+

Document all example targets.

+
+
--test NAME…​
+
+

Document the specified integration test. This flag may be specified multiple +times.

+
+
--tests
+
+

Document all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting test = false +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting test = true in the target settings.

+
+
--bench NAME…​
+
+

Document the specified benchmark. This flag may be specified multiple times.

+
+
--benches
+
+

Document all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting bench = +false in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting bench = true in the target +settings.

+
+
--all-targets
+
+

Document all targets.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Document for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Document artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Build documentation with custom CSS included from a given file:

    +
    +
    +
    cargo rustdoc --lib -- --extend-css extra.css
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-doc(1), rustdoc(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-search.html b/src/doc/src/commands/generated/cargo-search.html new file mode 100644 index 00000000000..5fb4bbb895c --- /dev/null +++ b/src/doc/src/commands/generated/cargo-search.html @@ -0,0 +1,160 @@ +

NAME

+
+

cargo-search - Search packages in crates.io

+
+
+

SYNOPSIS

+
+
+

cargo search [OPTIONS] [QUERY…​]

+
+
+
+
+

DESCRIPTION

+
+
+

This performs a textual search for crates on https://crates.io. The matching +crates will be displayed along with their description in TOML format suitable +for copying into a Cargo.toml manifest.

+
+
+
+
+

OPTIONS

+
+
+

Search Options

+
+
+
--limit LIMIT
+
+

Limit the number of results (default: 10, max: 100).

+
+
--index INDEX
+
+

The URL of the registry index to use.

+
+
--registry REGISTRY
+
+

Alternative registry to use.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Search for a package from crates.io:

    +
    +
    +
    cargo search serde
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-install(1), cargo-publish(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-test.html b/src/doc/src/commands/generated/cargo-test.html new file mode 100644 index 00000000000..418362fbd1f --- /dev/null +++ b/src/doc/src/commands/generated/cargo-test.html @@ -0,0 +1,545 @@ +

NAME

+
+

cargo-test - Execute unit and integration tests of a package

+
+
+

SYNOPSIS

+
+
+

cargo test [OPTIONS] [TESTNAME] [-- TEST-OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Compile and execute unit and integration tests.

+
+
+

The test filtering argument TESTNAME and all the arguments following the two +dashes (--) are passed to the test binaries and thus to libtest (rustc’s +built in unit-test and micro-benchmarking framework). If you’re passing +arguments to both Cargo and the binary, the ones after -- go to the binary, +the ones before go to Cargo. For details about libtest’s arguments see the +output of cargo test — --help. As an example, this will run all tests with +foo in their name on 3 threads in parallel:

+
+
+
+
cargo test foo -- --test-threads 3
+
+
+
+

Tests are built with the --test option to rustc which creates an +executable with a main function that automatically runs all functions +annotated with the #[test] attribute in multiple threads. The libtest +harness may be disabled by setting harness = false in the target manifest +settings, in which case your code will need to provide its own main function +to handle running tests.

+
+
+

Documentation tests are also run by default, which is handled by rustdoc. It +extracts code samples from documentation comments and executes them.

+
+
+
+
+

OPTIONS

+
+
+

Test Options

+
+
+
--no-run
+
+

Compile, but don’t run tests.

+
+
--no-fail-fast
+
+

Run all tests regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all +tests within the executable to completion, this flag only applies to +the executable as a whole.

+
+
+
+
+
+

Package Selection

+
+

By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (--all is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the workspace.default-members key in the root Cargo.toml +manifest.

+
+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Test only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.

+
+
--all
+
+

Test all members in the workspace.

+
+
--exclude SPEC…​
+
+

Exclude the specified packages. Must be used in conjunction with the +--all flag. This flag may be specified multiple times.

+
+
+
+
+
+

Target Selection

+
+

When no target selection options are given, cargo test will build the +following targets of the selected packages:

+
+
+
    +
  • +

    lib – used to link with binaries, examples, integration tests, and doc tests

    +
    • +
  • +

    bins (only if integration tests are built and required features are +available)

    +
    • +
  • +

    examples – to ensure they compile

    +
    • +
  • +

    lib as a unit test

    +
    • +
  • +

    bins as unit tests

    +
    • +
  • +

    integration tests

    +
    • +
  • +

    doc tests for the lib target

    +
    • +
+
+
+

The default behavior can be changed by setting the test flag for the target +in the manifest settings. Setting examples to test = true will build and run +the example as a test. Setting targets to test = false will stop them from +being tested by default. Target selection options that take a target by name +ignore the test flag and will always test the given target.

+
+
+

Doc tests for libraries may be disabled by setting doctest = false for the +library in the manifest.

+
+
+

Passing target selection flags will test only the +specified targets.

+
+
+
+
--lib
+
+

Test the package’s library.

+
+
--bin NAME…​
+
+

Test the specified binary. This flag may be specified multiple times.

+
+
--bins
+
+

Test all binary targets.

+
+
--example NAME…​
+
+

Test the specified example. This flag may be specified multiple times.

+
+
--examples
+
+

Test all example targets.

+
+
--test NAME…​
+
+

Test the specified integration test. This flag may be specified multiple +times.

+
+
--tests
+
+

Test all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting test = false +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting test = true in the target settings.

+
+
--bench NAME…​
+
+

Test the specified benchmark. This flag may be specified multiple times.

+
+
--benches
+
+

Test all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting bench = +false in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting bench = true in the target +settings.

+
+
--all-targets
+
+

Test all targets.

+
+
--doc
+
+

Test only the library’s documentation. This cannot be mixed with other +target options.

+
+
+
+
+
+

Feature Selection

+
+

When no feature options are given, the default feature is activated for +every selected package.

+
+
+
+
--features FEATURES
+
+

Space or comma separated list of features to activate. These features only +apply to the current directory’s package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax.

+
+
--all-features
+
+

Activate all available features of all selected packages.

+
+
--no-default-features
+
+

Do not activate the default feature of the current directory’s +package.

+
+
+
+
+
+

Compilation Options

+
+
+
--target TRIPLE
+
+

Test for the given architecture. The default is the host architecture.

+
+

The general format of the triple is <arch><sub>-<vendor>-<sys>-<abi> where:

+
+
+
    +
  • +

    arch = The base CPU architecture, for example x86_64, i686, arm, +thumb, mips, etc.

    +
    • +
  • +

    sub = The CPU sub-architecture, for example arm has v7, v7s, v5te, +etc.

    +
    • +
  • +

    vendor = The vendor, for example unknown, apple, pc, linux, etc.

    +
    • +
  • +

    sys = The system name, for example linux, windows, etc. none is +typically used for bare-metal without an OS.

    +
    • +
  • +

    abi = The ABI, for example gnu, android, eabi, etc.

    +
    • +
+
+
+
+
+

Some parameters may be omitted. Run rustc --print target-list for a list of +supported targets.

+
+
+

This may also be specified with the build.target +config value.

+
+
+
+
+
--release
+
+

Test artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection.

+
+
+
+
+
+

Output Options

+
+
+
--target-dir DIRECTORY
+
+

Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.

+
+
+
+
+
+

Display Options

+
+

By default the Rust test harness hides output from test execution to keep +results readable. Test output can be recovered (e.g. for debugging) by passing +--nocapture to the test binaries:

+
+
+
+
cargo test -- --nocapture
+
+
+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
--message-format FMT
+
+

The output format for diagnostic messages. Valid values:

+
+
    +
  • +

    human (default): Display in a human-readable text format.

    +
    • +
  • +

    json: Emit JSON messages to stdout.

    +
    • +
  • +

    short: Emit shorter, human-readable text messages.

    +
    • +
+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+

Miscellaneous Options

+
+

The --jobs argument affects the building of the test executable but does not +affect how many threads are used when running the tests. The Rust test harness +includes an option to control the number of threads used:

+
+
+
+
cargo test -j 2 -- --test-threads=2
+
+
+
+
+
-j N
+
--jobs N
+
+

Number of parallel jobs to run. May also be specified with the +build.jobs config value. Defaults to +the number of CPUs.

+
+
+
+
+
+
+
+

PROFILES

+
+
+

Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +the reference +for more details.

+
+
+

Profile selection depends on the target and crate being built. By default the +dev or test profiles are used. If the --release flag is given, then the +release or bench profiles are used.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
TargetDefault Profile--release Profile

lib, bin, example

dev

release

test, bench

test

bench

+
+

Dependencies use the dev/release profiles.

+
+
+

Unit tests are separate executable artifacts which use the test/bench +profiles. Example targets are built the same as with cargo build (using the +dev/release profiles) unless you are building them with the test harness +(by setting test = true in the manifest or using the --example flag) in +which case they use the test/bench profiles. Library targets are built +with the dev/release profiles when linked to an integration test, binary, +or doctest.

+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Execute all the unit and integration tests of the current package:

    +
    +
    +
    cargo test
    +
    +
    +
    2. +
  2. +

    Run only a specific test within a specific integration test:

    +
    +
    +
    cargo test --test int_test_name -- modname::test_name
    +
    +
    +
    3. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-bench(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-uninstall.html b/src/doc/src/commands/generated/cargo-uninstall.html new file mode 100644 index 00000000000..05db5837f3a --- /dev/null +++ b/src/doc/src/commands/generated/cargo-uninstall.html @@ -0,0 +1,183 @@ +

NAME

+
+

cargo-uninstall - Remove a Rust binary

+
+
+

SYNOPSIS

+
+
+

cargo uninstall [OPTIONS] [SPEC…​]

+
+
+
+
+

DESCRIPTION

+
+
+

This command removes a package installed with cargo-install(1). The SPEC +argument is a package ID specification of the package to remove (see +cargo-pkgid(1)).

+
+
+

By default all binaries are removed for a crate but the --bin and +--example flags can be used to only remove particular binaries.

+
+
+

The installation root is determined, in order of precedence:

+
+
+
    +
  • +

    --root option

    +
    • +
  • +

    CARGO_INSTALL_ROOT environment variable

    +
    • +
  • +

    install.root Cargo config value

    +
    • +
  • +

    CARGO_HOME environment variable

    +
    • +
  • +

    $HOME/.cargo

    +
    • +
+
+
+
+
+

OPTIONS

+
+
+

Install Options

+
+
+
-p
+
--package SPEC…​
+
+

Package to uninstall.

+
+
--bin NAME…​
+
+

Only uninstall the binary NAME.

+
+
--root DIR
+
+

Directory to uninstall packages from.

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Uninstall a previously installed package.

    +
    +
    +
    cargo uninstall ripgrep
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-install(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-update.html b/src/doc/src/commands/generated/cargo-update.html new file mode 100644 index 00000000000..78a583eeb21 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-update.html @@ -0,0 +1,212 @@ +

NAME

+
+

cargo-update - Update dependencies as recorded in the local lock file

+
+
+

SYNOPSIS

+
+
+

cargo update [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will update dependencies in the Cargo.lock file to the latest +version. It requires that the Cargo.lock file already exists as generated +by commands such as cargo-build(1) or cargo-generate-lockfile(1).

+
+
+
+
+

OPTIONS

+
+
+

Update Options

+
+
+
-p SPEC…​
+
--package SPEC…​
+
+

Update only the specified packages. This flag may be specified +multiple times. See cargo-pkgid(1) for the SPEC format.

+
+

If packages are specified with the -p flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions.

+
+
+

If -p is not specified, all dependencies are updated.

+
+
+
--aggressive
+
+

When used with -p, dependencies of SPEC are forced to update as well. +Cannot be used with --precise.

+
+
--precise PRECISE
+
+

When used with -p, allows you to specify a specific version number to +set the package to. If the package comes from a git repository, this can +be a git revision (such as a SHA hash or tag).

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Update all dependencies in the lockfile:

    +
    +
    +
    cargo update
    +
    +
    +
    2. +
  2. +

    Update only specific dependencies:

    +
    +
    +
    cargo update -p foo -p bar
    +
    +
    +
    3. +
  3. +

    Set a specific dependency to a specific version:

    +
    +
    +
    cargo update -p foo --precise 1.2.3
    +
    +
    +
    4. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-generate-lockfile(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-verify-project.html b/src/doc/src/commands/generated/cargo-verify-project.html new file mode 100644 index 00000000000..c137859c1f2 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-verify-project.html @@ -0,0 +1,174 @@ +

NAME

+
+

cargo-verify-project - Check correctness of crate manifest

+
+
+

SYNOPSIS

+
+
+

cargo verify-project [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

This command will parse the local manifest and check its validity. It emits a +JSON object with the result. A successful validation will display:

+
+
+
+
{"success":"true"}
+
+
+
+

An invalid workspace will display:

+
+
+
+
{"invalid":"human-readable error message"}
+
+
+
+
+
+

OPTIONS

+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--manifest-path PATH
+
+

Path to the Cargo.toml file. By default, Cargo searches in the current +directory or any parent directory for the Cargo.toml file.

+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

The workspace is OK.

+
+
1
+
+

The workspace is invalid.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Check the current workspace for errors:

    +
    +
    +
    cargo verify-project
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-package(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-version.html b/src/doc/src/commands/generated/cargo-version.html new file mode 100644 index 00000000000..32fb5fc3347 --- /dev/null +++ b/src/doc/src/commands/generated/cargo-version.html @@ -0,0 +1,76 @@ +

NAME

+
+

cargo-version - Show version information

+
+
+

SYNOPSIS

+
+
+

cargo version [OPTIONS]

+
+
+
+
+

DESCRIPTION

+
+
+

Displays the version of Cargo.

+
+
+
+
+

OPTIONS

+
+
+
+
-v
+
--verbose
+
+

Display additional version information.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Display the version:

    +
    +
    +
    cargo version
    +
    +
    +
    2. +
  2. +

    The version is also available via flags:

    +
    +
    +
    cargo --version
+cargo -V
    +
    +
    +
    3. +
  3. +

    Display extra version information:

    +
    +
    +
    cargo -Vv
    +
    +
    +
    4. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo-yank.html b/src/doc/src/commands/generated/cargo-yank.html new file mode 100644 index 00000000000..26b1f008c8f --- /dev/null +++ b/src/doc/src/commands/generated/cargo-yank.html @@ -0,0 +1,181 @@ +

NAME

+
+

cargo-yank - Remove a pushed crate from the index

+
+
+

SYNOPSIS

+
+
+

cargo yank [OPTIONS] --vers VERSION [CRATE]

+
+
+
+
+

DESCRIPTION

+
+
+

The yank command removes a previously published crate’s version from the +server’s index. This command does not delete any data, and the crate will +still be available for download via the registry’s download link.

+
+
+

Note that existing crates locked to a yanked version will still be able to +download the yanked version to use it. Cargo will, however, not allow any new +crates to be locked to any yanked version.

+
+
+

This command requires you to be authenticated with either the --token option +or using cargo-login(1).

+
+
+

If the crate name is not specified, it will use the package name from the +current directory.

+
+
+
+
+

OPTIONS

+
+
+

Owner Options

+
+
+
--vers VERSION
+
+

The version to yank or un-yank.

+
+
--undo
+
+

Undo a yank, putting a version back into the index.

+
+
--token TOKEN
+
+

API token to use when authenticating.

+
+
--index INDEX
+
+

The URL of the registry index to use.

+
+
--registry REGISTRY
+
+

Alternative registry to use.

+
+

This option is unstable and available only on the nightly channel and requires +the -Z unstable-options flag to enable.

+
+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Yank a crate from the index:

    +
    +
    +
    cargo yank --vers 1.0.7 foo
    +
    +
    +
    2. +
+
+
+
+
+

SEE ALSO

+
+
+

cargo(1), cargo-login(1), cargo-publish(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/generated/cargo.html b/src/doc/src/commands/generated/cargo.html new file mode 100644 index 00000000000..63ae81406ea --- /dev/null +++ b/src/doc/src/commands/generated/cargo.html @@ -0,0 +1,433 @@ +

NAME

+
+

cargo - The Rust package manager

+
+
+

SYNOPSIS

+
+
+

cargo [OPTIONS] COMMAND [ARGS]
+cargo [OPTIONS] --version
+cargo [OPTIONS] --list
+cargo [OPTIONS] --help
+cargo [OPTIONS] --explain CODE

+
+
+
+
+

DESCRIPTION

+
+
+

This program is a package manager and build tool for the Rust language, +available at http://rust-lang.org.

+
+
+
+
+

COMMANDS

+
+
+

Build Commands

+
+
+
cargo-bench(1)
+
+

Execute benchmarks of a package.

+
+
cargo-build(1)
+
+

Compile a package.

+
+
cargo-check(1)
+
+

Check a local package and all of its dependencies for errors.

+
+
cargo-clean(1)
+
+

Remove artifacts that Cargo has generated in the past.

+
+
cargo-doc(1)
+
+

Build a package’s documentation.

+
+
cargo-fetch(1)
+
+

Fetch dependencies of a package from the network.

+
+
cargo-fix(1)
+
+

Automatically fix lint warnings reported by rustc.

+
+
cargo-run(1)
+
+

Run a binary of the local package.

+
+
cargo-rustc(1)
+
+

Compile a package, and pass extra options to the compiler.

+
+
cargo-rustdoc(1)
+
+

Build a package’s documentation, using specified custom flags.

+
+
cargo-test(1)
+
+

Execute unit and integration tests of a package.

+
+
+
+
+
+

Manifest Commands

+
+
+
cargo-generate-lockfile(1)
+
+

Generate Cargo.lock for a project.

+
+
cargo-locate-project(1)
+
+

Print a JSON representation of a Cargo.toml file’s location.

+
+
cargo-metadata(1)
+
+

Output the resolved dependencies of a package, the concrete used versions +including overrides, in machine-readable format.

+
+
cargo-pkgid(1)
+
+

Print a fully qualified package specification.

+
+
cargo-update(1)
+
+

Update dependencies as recorded in the local lock file.

+
+
cargo-verify-project(1)
+
+

Check correctness of crate manifest.

+
+
+
+
+
+

Package Commands

+
+
+
cargo-init(1)
+
+

Create a new Cargo package in an existing directory.

+
+
cargo-install(1)
+
+

Build and install a Rust binary.

+
+
cargo-new(1)
+
+

Create a new Cargo package.

+
+
cargo-search(1)
+
+

Search packages in crates.io.

+
+
cargo-uninstall(1)
+
+

Remove a Rust binary.

+
+
+
+
+
+

Publishing Commands

+
+
+
cargo-login(1)
+
+

Save an API token from the registry locally.

+
+
cargo-owner(1)
+
+

Manage the owners of a crate on the registry.

+
+
cargo-package(1)
+
+

Assemble the local package into a distributable tarball.

+
+
cargo-publish(1)
+
+

Upload a package to the registry.

+
+
cargo-yank(1)
+
+

Remove a pushed crate from the index.

+
+
+
+
+
+

General Commands

+
+
+
cargo-help(1)
+
+

Display help information about Cargo.

+
+
cargo-version(1)
+
+

Show version information.

+
+
+
+
+
+
+
+

OPTIONS

+
+
+

Special Options

+
+
+
-V
+
--version
+
+

Print version info and exit. If used with --verbose, prints extra +information.

+
+
--list
+
+

List all installed Cargo subcommands. If used with --verbose, prints +extra information.

+
+
--explain CODE
+
+

Run rustc --explain CODE which will print out a detailed explanation of +an error message (for example, E0004).

+
+
+
+
+
+

Display Options

+
+
+
-v
+
--verbose
+
+

Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.

+
+
-q
+
--quiet
+
+

No output printed to stdout.

+
+
--color WHEN
+
+

Control when colored output is used. Valid values:

+
+
    +
  • +

    auto (default): Automatically detect if color support is available on the +terminal.

    +
    • +
  • +

    always: Always display colors.

    +
    • +
  • +

    never: Never display colors.

    +
    • +
+
+
+

May also be specified with the term.color +config value.

+
+
+
+
+
+
+

Manifest Options

+
+
+
--frozen
+
--locked
+
+

Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+
+

These may be used in environments where you want to assert that the +Cargo.lock file is up-to-date (such as a CI build) or want to avoid network +access.

+
+
+
+
+
+
+

Common Options

+
+
+
-h
+
--help
+
+

Prints help information.

+
+
-Z FLAG…​
+
+

Unstable (nightly-only) flags to Cargo. Run cargo -Z help for +details.

+
+
+
+
+
+
+
+

ENVIRONMENT

+
+
+

See the reference for +details on environment variables that Cargo reads.

+
+
+
+
+

Exit Status

+
+
+
+
0
+
+

Cargo succeeded.

+
+
101
+
+

Cargo failed to complete.

+
+
+
+
+
+
+

FILES

+
+
+
+
~/.cargo/
+
+

Default location for Cargo’s "home" directory where it stores various +files. The location can be changed with the CARGO_HOME environment +variable.

+
+
$CARGO_HOME/bin/
+
+

Binaries installed by cargo-install(1) will be located here. If using +rustup, executables distributed with Rust are also located here.

+
+
$CARGO_HOME/config
+
+

The global configuration file. See the reference +for more information about configuration files.

+
+
.cargo/config
+
+

Cargo automatically searches for a file named .cargo/config in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file.

+
+
$CARGO_HOME/credentials
+
+

Private authentication information for logging in to a registry.

+
+
$CARGO_HOME/registry/
+
+

This directory contains cached downloads of the registry index and any +downloaded dependencies.

+
+
$CARGO_HOME/git/
+
+

This directory contains cached downloads of git dependencies.

+
+
+
+
+
+
+

EXAMPLES

+
+
+
    +
  1. +

    Build a local package and all of its dependencies:

    +
    +
    +
    cargo build
    +
    +
    +
    2. +
  2. +

    Build a package with optimizations:

    +
    +
    +
    cargo build --release
    +
    +
    +
    3. +
  3. +

    Run tests for a cross-compiled target:

    +
    +
    +
    cargo test --target i686-unknown-linux-gnu
    +
    +
    +
    4. +
  4. +

    Create a new package that builds an executable:

    +
    +
    +
    cargo new foobar
    +
    +
    +
    5. +
  5. +

    Create a package in the current directory:

    +
    +
    +
    mkdir foo && cd foo
+cargo init .
    +
    +
    +
    6. +
  6. +

    Learn about a command’s options and usage:

    +
    +
    +
    cargo help clean
    +
    +
    +
    7. +
+
+
+
+
+

BUGS

+
+
+

See https://github.com/rust-lang/cargo/issues for issues.

+
+
+
+
+

SEE ALSO

+
+
+

rustc(1), rustdoc(1)

+
+
+
\ No newline at end of file diff --git a/src/doc/src/commands/index.md b/src/doc/src/commands/index.md new file mode 100644 index 00000000000..204935d7ef8 --- /dev/null +++ b/src/doc/src/commands/index.md @@ -0,0 +1,3 @@ +# cargo +{{#include command-common.html}} +{{#include generated/cargo.html}} diff --git a/src/doc/src/commands/manifest-commands.md b/src/doc/src/commands/manifest-commands.md new file mode 100644 index 00000000000..cd803bdc379 --- /dev/null +++ b/src/doc/src/commands/manifest-commands.md @@ -0,0 +1 @@ +# Manifest Commands diff --git a/src/doc/src/commands/package-commands.md b/src/doc/src/commands/package-commands.md new file mode 100644 index 00000000000..f528a2571d0 --- /dev/null +++ b/src/doc/src/commands/package-commands.md @@ -0,0 +1 @@ +# Package Commands diff --git a/src/doc/src/commands/publishing-commands.md b/src/doc/src/commands/publishing-commands.md new file mode 100644 index 00000000000..e32bf3c16f9 --- /dev/null +++ b/src/doc/src/commands/publishing-commands.md @@ -0,0 +1 @@ +# Publishing Commands diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index 74c1675cd06..83fc241a8ee 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -1,143 +1,553 @@ -.TH "CARGO\-BENCH" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-bench +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-BENCH" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-bench \- Execute benchmarks of a package -.SH SYNOPSIS -.PP -\f[I]cargo bench\f[] [OPTIONS] [\-\-] [...] -.SH DESCRIPTION -.PP -Execute all benchmarks of a local package. -.PP -All of the trailing arguments are passed to the benchmark binaries -generated for filtering benchmarks and generally providing options -configuring how they run. -.PP -If the \f[B]\-\-package\f[] argument is given, then \f[I]SPEC\f[] is a -package id specification which indicates which package should be built. -If it is not given, then the current package is built. -For more information on \f[I]SPEC\f[] and its format, see the "cargo -help pkgid" command. -.PP -The \f[B]\-\-jobs\f[] argument affects the building of the benchmark -executable but does not affect how many jobs are used when running the +.SH "SYNOPSIS" +.sp +\fBcargo bench [\fIOPTIONS\fP] [BENCHNAME] [\-\- \fIBENCH\-OPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +Compile and execute benchmarks. +.sp +The benchmark filtering argument \fBBENCHNAME\fP and all the arguments following +the two dashes (\fB\-\-\fP) are passed to the benchmark binaries and thus to +\fIlibtest\fP (rustc\(cqs built in unit\-test and micro\-benchmarking framework). If +you\(cqre passing arguments to both Cargo and the binary, the ones after \fB\-\-\fP go +to the binary, the ones before go to Cargo. For details about libtest\(cqs +arguments see the output of \fBcargo bench \(em \-\-help\fP. As an example, this will +run only the benchmark named \fBfoo\fP (and skip other similarly named benchmarks +like \fBfoobar\fP): +.sp +.if n .RS 4 +.nf +cargo bench \-\- foo \-\-exact +.fi +.if n .RE +.sp +Benchmarks are built with the \fB\-\-test\fP option to \fBrustc\fP which creates an +executable with a \fBmain\fP function that automatically runs all functions +annotated with the \fB#[bench]\fP attribute. The libtest harness may be disabled +by setting \fBharness = false\fP in the target manifest settings, in which case +your code will need to provide its own \fBmain\fP function to handle running benchmarks. -.PP -Compilation can be customized with the \[aq]bench\[aq] profile in the +.SH "OPTIONS" +.SS "Benchmark Options" +.sp +\fB\-\-no\-run\fP +.RS 4 +Compile, but don\(cqt run benchmarks. +.RE +.sp +\fB\-\-no\-fail\-fast\fP +.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" +.sp +By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (\fB\-\-all\fP is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the \fBworkspace.default\-members\fP key in the root \fBCargo.toml\fP manifest. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-lib -Benchmark only this package\[aq]s library. -.RS -.RE -.TP -.B \-\-bin \f[I]NAME\f[] -Benchmark only the specified binary. -.RS -.RE -.TP -.B \-\-example \f[I]NAME\f[] -Benchmark only the specified example. -.RS -.RE -.TP -.B \-\-test \f[I]NAME\f[] -Benchmark only the specified test target. -.RS -.RE -.TP -.B \-\-bench \f[I]NAME\f[] -Benchmark only the specified bench target. -.RS -.RE -.TP -.B \-\-no\-run -Compile, but don\[aq]t run benchmarks. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC ...\f[] -Package to benchmarks for. -.RS -.RE -.TP -.B \-j \f[I]IN\f[], \-\-jobs \f[I]IN\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-release -Build artifacts in release mode, with optimizations. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space\-separated list of features to also build. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not build the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Build for the target triple. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the Cargo.toml to compile. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Benchmark only the specified packages. See \fBcargo\-pkgid\fP(1) for the +SPEC format. This flag may be specified multiple times. +.RE +.sp +\fB\-\-all\fP +.RS 4 +Benchmark all members in the workspace. +.RE +.sp +\fB\-\-exclude\fP \fISPEC\fP... +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-all\fP flag. This flag may be specified multiple times. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo bench\fP will build the +following targets of the selected packages: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +lib – used to link with binaries and benchmarks +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +bins (only if benchmark targets are built and required features are +available) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +lib as a benchmark +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +bins as benchmarks +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +benchmark targets +.RE +.sp +The default behavior can be changed by setting the \fBbench\fP flag for the target +in the manifest settings. Setting examples to \fBbench = true\fP will build and +run the example as a benchmark. Setting targets to \fBbench = false\fP will stop +them from being benchmarked by default. Target selection options that take a +target by name ignore the \fBbench\fP flag and will always benchmark the given +target. +.sp +Passing target selection flags will benchmark only the +specified targets. +.sp +\fB\-\-lib\fP +.RS 4 +Benchmark the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Benchmark the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Benchmark all binary targets. +.RE +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Benchmark the specified example. This flag may be specified multiple times. +.RE +.sp +\fB\-\-examples\fP +.RS 4 +Benchmark all example targets. +.RE +.sp +\fB\-\-test\fP \fINAME\fP... +.RS 4 +Benchmark the specified integration test. This flag may be specified multiple +times. +.RE +.sp +\fB\-\-tests\fP +.RS 4 +Benchmark all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting \fBtest = false\fP +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting \fBtest = true\fP in the target settings. +.RE +.sp +\fB\-\-bench\fP \fINAME\fP... +.RS 4 +Benchmark the specified benchmark. This flag may be specified multiple times. +.RE +.sp +\fB\-\-benches\fP +.RS 4 +Benchmark all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting \fBbench = +false\fP in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting \fBbench = true\fP in the target +settings. +.RE +.sp +\fB\-\-all\-targets\fP +.RS 4 +Benchmark all targets. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Benchmark for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +By default the Rust test harness hides output from benchmark execution to keep +results readable. Benchmark output can be recovered (e.g. for debugging) by +passing \fB\-\-nocapture\fP to the benchmark binaries: +.sp +.if n .RS 4 +.nf +cargo bench \-\- \-\-nocapture +.fi +.if n .RE +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. .RE -.SH EXAMPLES -.PP -Execute all the benchmarks of the current package -.IP +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +The \fB\-\-jobs\fP argument affects the building of the benchmark executable but +does not affect how many threads are used when running the benchmarks. The +Rust test harness runs benchmarks serially in a single thread. +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Benchmarks are always built with the \fBbench\fP profile. Binary and lib targets +are built separately as benchmarks with the \fBbench\fP profile. Library targets +are built with the \fBrelease\fP profiles when linked to binaries and benchmarks. +Dependencies use the \fBrelease\fP profile. +.sp +If you need a debug build of a benchmark, try building it with +\fBcargo\-build\fP(1) which will use the \fBtest\fP profile which is by default +unoptimized and includes debug information. You can then run the debug\-enabled +benchmark manually. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Build and execute all the benchmarks of the current package: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ bench -\f[] +cargo bench .fi -.PP -Execute the BENCH benchmark -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Run only a specific benchmark within a specific benchmark target: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ bench\ \-\-bench\ BENCH -\f[] +cargo bench \-\-bench bench_name \-\- modname::some_benchmark .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-build(1), cargo\-test(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-test\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index 13c5ac6380c..27f99a956a4 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -1,132 +1,495 @@ -.TH "CARGO\-BUILD" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-build +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-BUILD" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-build \- Compile the current package -.SH SYNOPSIS -.PP -\f[I]cargo build\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Compile a local package and all of its dependencies. -.PP -If the \f[B]\-\-package\f[] argument is given, then \f[I]SPEC\f[] is a -package id specification which indicates which package should be built. -If it is not given, then the current package is built. -For more information on \f[I]SPEC\f[] and its format, see the "cargo -help pkgid" command. -.PP -Compilation can be configured via the use of profiles which are -configured in the manifest. -The default profile for this command is \f[I]dev\f[], but passing the -\f[B]\-\-release\f[] flag will use the \f[I]release\f[] profile instead. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC ...\f[] -Package to build. -.RS -.RE -.TP -.B \-j \f[I]IN\f[], \-\-jobs \f[I]IN\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-lib -Build only this package\[aq]s library. -.RS -.RE -.TP -.B \-\-bin \f[I]NAME\f[] -Build only the specified binary. -.RS -.RE -.TP -.B \-\-example \f[I]NAME\f[] -Build only the specified example. -.RS -.RE -.TP -.B \-\-test \f[I]NAME\f[] -Build only the specified test target. -.RS -.RE -.TP -.B \-\-bench \f[I]NAME\f[] -Build only the specified benchmark target. -.RS -.RE -.TP -.B \-\-release -Build artifacts in release mode, with optimizations. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space\-separated list of features to also build. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not build the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Build for the target triple. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the Cargo.toml to compile. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.SH "SYNOPSIS" +.sp +\fBcargo build [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +Compile local packages and all of their dependencies. +.SH "OPTIONS" +.SS "Package Selection" +.sp +By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (\fB\-\-all\fP is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the \fBworkspace.default\-members\fP key in the root \fBCargo.toml\fP +manifest. +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Build only the specified packages. See \fBcargo\-pkgid\fP(1) for the +SPEC format. This flag may be specified multiple times. +.RE +.sp +\fB\-\-all\fP +.RS 4 +Build all members in the workspace. +.RE +.sp +\fB\-\-exclude\fP \fISPEC\fP... +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-all\fP flag. This flag may be specified multiple times. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo build\fP will build all +binary and library targets of the selected packages. Binaries are skipped if +they have \fBrequired\-features\fP that are missing. +.sp +Passing target selection flags will build only the +specified targets. +.sp +\fB\-\-lib\fP +.RS 4 +Build the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Build the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Build all binary targets. +.RE +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Build the specified example. This flag may be specified multiple times. +.RE +.sp +\fB\-\-examples\fP +.RS 4 +Build all example targets. +.RE +.sp +\fB\-\-test\fP \fINAME\fP... +.RS 4 +Build the specified integration test. This flag may be specified multiple +times. +.RE +.sp +\fB\-\-tests\fP +.RS 4 +Build all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting \fBtest = false\fP +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting \fBtest = true\fP in the target settings. +.RE +.sp +\fB\-\-bench\fP \fINAME\fP... +.RS 4 +Build the specified benchmark. This flag may be specified multiple times. +.RE +.sp +\fB\-\-benches\fP +.RS 4 +Build all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting \fBbench = +false\fP in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting \fBbench = true\fP in the target +settings. +.RE +.sp +\fB\-\-all\-targets\fP +.RS 4 +Build all targets. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Build for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Build artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.sp +\fB\-\-out\-dir\fP \fIDIRECTORY\fP +.RS 4 +Copy final artifacts to this directory. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. +.RE .RE -.SH EXAMPLES -.PP -Build a local package and all of its dependencies -.IP +.sp +\fB\-\-build\-plan\fP +.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 nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Build the local package and all of its dependencies: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ build -\f[] +cargo build .fi -.PP -Build a package with optimizations -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Build with optimizations: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ build\ \-\-release -\f[] +cargo build \-\-release .fi -.SH SEE ALSO -.PP -cargo(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-rustc\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index 9575c3c6cd8..009b8104739 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -1,132 +1,491 @@ -.TH "CARGO\-CHECK" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-check +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-CHECK" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-check \- Check the current package -.SH SYNOPSIS -.PP -\f[I]cargo check\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Check a local package and all of its dependencies. -.PP -If the \f[B]\-\-package\f[] argument is given, then \f[I]SPEC\f[] is a -package id specification which indicates which package should be checked. -If it is not given, then the current package is checked. -For more information on \f[I]SPEC\f[] and its format, see the "cargo -help pkgid" command. -.PP -Compilation can be configured via the use of profiles which are -configured in the manifest. -The default profile for this command is \f[I]dev\f[], but passing the -\f[B]\-\-release\f[] flag will use the \f[I]release\f[] profile instead. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC ...\f[] -Package to check. -.RS -.RE -.TP -.B \-j \f[I]IN\f[], \-\-jobs \f[I]IN\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-lib -Check only this package\[aq]s library. -.RS -.RE -.TP -.B \-\-bin \f[I]NAME\f[] -Check only the specified binary. -.RS -.RE -.TP -.B \-\-example \f[I]NAME\f[] -Check only the specified example. -.RS -.RE -.TP -.B \-\-test \f[I]NAME\f[] -Check only the specified test target. -.RS -.RE -.TP -.B \-\-bench \f[I]NAME\f[] -Check only the specified benchmark target. -.RS -.RE -.TP -.B \-\-release -Check artifacts in release mode. -.RS -.RE -.TP -.B \-\-all\-features -Check with all available features. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space\-separated list of features to also check. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not check the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Check for the target triple. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the Cargo.toml to compile. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.SH "SYNOPSIS" +.sp +\fBcargo check [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +Check a local package and all of its dependencies for errors. This will +essentially compile the packages without performing the final step of code +generation, which is faster than running \fBcargo build\fP. The compiler will save +metadata files to disk so that future runs will reuse them if the source has +not been modified. +.SH "OPTIONS" +.SS "Package Selection" +.sp +By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (\fB\-\-all\fP is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the \fBworkspace.default\-members\fP key in the root \fBCargo.toml\fP +manifest. +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Check only the specified packages. See \fBcargo\-pkgid\fP(1) for the +SPEC format. This flag may be specified multiple times. +.RE +.sp +\fB\-\-all\fP +.RS 4 +Check all members in the workspace. +.RE +.sp +\fB\-\-exclude\fP \fISPEC\fP... +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-all\fP flag. This flag may be specified multiple times. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo check\fP will check all +binary and library targets of the selected packages. Binaries are skipped if +they have \fBrequired\-features\fP that are missing. +.sp +Passing target selection flags will check only the +specified targets. +.sp +\fB\-\-lib\fP +.RS 4 +Check the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Check the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Check all binary targets. +.RE +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Check the specified example. This flag may be specified multiple times. +.RE +.sp +\fB\-\-examples\fP +.RS 4 +Check all example targets. +.RE +.sp +\fB\-\-test\fP \fINAME\fP... +.RS 4 +Check the specified integration test. This flag may be specified multiple +times. +.RE +.sp +\fB\-\-tests\fP +.RS 4 +Check all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting \fBtest = false\fP +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting \fBtest = true\fP in the target settings. +.RE +.sp +\fB\-\-bench\fP \fINAME\fP... +.RS 4 +Check the specified benchmark. This flag may be specified multiple times. +.RE +.sp +\fB\-\-benches\fP +.RS 4 +Check all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting \fBbench = +false\fP in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting \fBbench = true\fP in the target +settings. +.RE +.sp +\fB\-\-all\-targets\fP +.RS 4 +Check all targets. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Check for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Check artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.sp +\fB\-\-profile\fP \fINAME\fP +.RS 4 +Changes check behavior. Currently only \fBtest\fP is +supported, which will check with the +\fB#[cfg(test)]\fP attribute enabled. This is useful to have it +check unit tests which are usually excluded via +the \fBcfg\fP attribute. This does not change the actual profile used. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. .RE -.SH EXAMPLES -.PP -Check a local package and all of its dependencies -.IP +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Check the local package for errors: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ check -\f[] +cargo check .fi -.PP -Check a package with optimizations -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Check all targets, including unit tests: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ check\ \-\-release -\f[] +cargo check \-\-all\-targets \-\-profile=test .fi -.SH SEE ALSO -.PP -cargo(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-clean.1 b/src/etc/man/cargo-clean.1 index 6777c984f17..4f9eb3da1b5 100644 --- a/src/etc/man/cargo-clean.1 +++ b/src/etc/man/cargo-clean.1 @@ -1,82 +1,287 @@ -.TH "CARGO\-CLEAN" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-clean +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-CLEAN" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-clean \- Remove generated artifacts -.SH SYNOPSIS -.PP -\f[I]cargo clean\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Remove artifacts that cargo has generated in the past. -.PP -If the \f[B]\-\-package\f[] argument is given, then \f[I]SPEC\f[] is a -package id specification which indicates which package should be built. -If it is not given, then the current package is built. -For more information on \f[I]SPEC\f[] and its format, see the "cargo -help pkgid" command. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC ...\f[] -Package to clean artifacts for. -.RS -.RE -.TP -.B \-\-manifest\-path PATH -Path to the manifest to the package to clean. -.RS -.RE -.TP -.B \-\-target TRIPLE -Target triple to clean output for (default all). -.RS -.RE -.TP -.B \-\-release -Whether or not to clean release artifacts. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.SH "SYNOPSIS" +.sp +\fBcargo clean [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +Remove artifacts from the target directory that Cargo has generated in the +past. +.sp +With no options, \fBcargo clean\fP will delete the entire target directory. +.SH "OPTIONS" +.SS "Package Selection" +.sp +When no packages are selected, all packages and all dependencies in the +workspace are cleaned. +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Clean only the specified packages. This flag may be specified +multiple times. See \fBcargo\-pkgid\fP(1) for the SPEC format. +.RE +.SS "Clean Options" +.sp +\fB\-\-doc\fP +.RS 4 +This option will cause \fBcargo clean\fP to remove only the \fBdoc\fP directory in +the target directory. +.RE +.sp +\fB\-\-release\fP +.RS 4 +Clean all artifacts that were built with the \fBrelease\fP or \fBbench\fP +profiles. +.RE +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Clean for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. .RE -.SH EXAMPLES -.PP -Remove local package generated artifacts -.IP +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Remove the entire target directory: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ clean -\f[] +cargo clean .fi -.PP -Clean release artifacts -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Remove only the release artifacts: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ clean\ \-\-release -\f[] +cargo clean \-\-release .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-build(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index d4af424531a..e68c4455483 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -1,109 +1,438 @@ -.TH "CARGO\-DOC" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-doc \- Build a package\[aq]s documentation -.SH SYNOPSIS -.PP -\f[I]cargo doc\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Build a package\[aq]s documentation. -.PP -By default the documentation for the local package and all dependencies -is built. -The output is all placed in \[aq]target/doc\[aq] in rustdoc\[aq]s usual -format. -.PP -If the \f[B]\-\-package\f[] argument is given, then \f[I]SPEC\f[] is a -package id specification which indicates which package should be built. -If it is not given, then the current package is built. -For more information on \f[I]SPEC\f[] and its format, see the "cargo -help pkgid" command. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC ...\f[] -Package to document. -.RS -.RE -.TP -.B \-\-open -Opens the docs in a browser after the operation. -.RS -.RE -.TP -.B \-\-no\-deps -Don\[aq]t build documentation for dependencies. -.RS -.RE -.TP -.B \-j \f[I]N\f[], \-\-jobs \f[I]N\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-release -Build artifacts in release mode, with optimizations. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space\-separated list of features to also build. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not build the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Build for the target triple. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the Cargo.toml to compile. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-doc +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-DOC" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-doc \- Build a package\(aqs documentation +.SH "SYNOPSIS" +.sp +\fBcargo doc [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +Build the documentation for the local package and all dependencies. The output +is placed in \fBtarget/doc\fP in rustdoc\(cqs usual format. +.SH "OPTIONS" +.SS "Documentation Options" +.sp +\fB\-\-open\fP +.RS 4 +Open the docs in a browser after building them. +.RE +.sp +\fB\-\-no\-deps\fP +.RS 4 +Do not build documentation for dependencies. +.RE +.sp +\fB\-\-document\-private\-items\fP +.RS 4 +Include non\-public items in the documentation. +.RE +.SS "Package Selection" +.sp +By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (\fB\-\-all\fP is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the \fBworkspace.default\-members\fP key in the root \fBCargo.toml\fP +manifest. +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Document only the specified packages. See \fBcargo\-pkgid\fP(1) for the +SPEC format. This flag may be specified multiple times. +.RE +.sp +\fB\-\-all\fP +.RS 4 +Document all members in the workspace. +.RE +.sp +\fB\-\-exclude\fP \fISPEC\fP... +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-all\fP flag. This flag may be specified multiple times. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo doc\fP will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +\fBrequired\-features\fP that are missing. +.sp +The default behavior can be changed by setting \fBdoc = false\fP for the target in +the manifest settings. Using target selection options will ignore the \fBdoc\fP +flag and will always document the given target. +.sp +\fB\-\-lib\fP +.RS 4 +Document the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Document the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Document all binary targets. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Document for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Document artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. .RE -.SH EXAMPLES -.PP -Build a local package documentation in \[aq]target/doc\[aq] -.IP +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Build the local package documentation and its dependencies and output to +\fBtarget/doc\fP. +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ doc -\f[] +cargo doc .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-build(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-rustdoc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-fetch.1 b/src/etc/man/cargo-fetch.1 index 96c49ab8801..d4605ec96b5 100644 --- a/src/etc/man/cargo-fetch.1 +++ b/src/etc/man/cargo-fetch.1 @@ -1,52 +1,243 @@ -.TH "CARGO\-FETCH" "1" "July 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-fetch +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-FETCH" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-fetch \- Fetch dependencies of a package from the network -.SH SYNOPSIS -.PP -\f[I]cargo fetch\f[] [OPTIONS] -.SH DESCRIPTION -.PP -If a lockfile is available, this command will ensure that all of the git -dependencies and/or registries dependencies are downloaded and locally -available. The network is never touched after a `cargo fetch` unless -the lockfile changes. - -If the lockfile is not available, then this is the equivalent of -`cargo generate-lockfile`. A lockfile is generated and dependencies are also -all updated. -.PP -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-manifest-path \f[I]PATH\f[] -Path to the manifest to fetch dependencies for. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.SH "SYNOPSIS" +.sp +\fBcargo fetch [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +If a \fBCargo.lock\fP file is available, this command will ensure that all of the +git dependencies and/or registry dependencies are downloaded and locally +available. Subsequent Cargo commands never touch the network after a \fBcargo +fetch\fP unless the lock file changes. +.sp +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. +.sp +If \fB\-\-target\fP is not specified, then all target dependencies are fetched. +.SH "OPTIONS" +.SS "Fetch options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Fetch for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-update(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Fetch all dependencies: +.sp +.if n .RS 4 +.nf +cargo fetch +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-update\fP(1), \fBcargo\-generate\-lockfile\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 new file mode 100644 index 00000000000..5975a5fd4ac --- /dev/null +++ b/src/etc/man/cargo-fix.1 @@ -0,0 +1,578 @@ +'\" t +.\" Title: cargo-fix +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-FIX" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-fix \- Automatically fix lint warnings reported by rustc +.SH "SYNOPSIS" +.sp +\fBcargo fix [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +This Cargo subcommand will automatically take rustc\(cqs suggestions from +diagnostics like warnings and apply them to your source code. This is intended +to help automate tasks that rustc itself already knows how to tell you to fix! +The \fBcargo fix\fP subcommand is also being developed for the Rust 2018 edition +to provide code the ability to easily opt\-in to the new edition without having +to worry about any breakage. +.sp +Executing \fBcargo fix\fP will under the hood execute \fBcargo\-check\fP(1). Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you\(cqd like to prepare for the 2018 edition, you can do so by +executing: +.sp +.if n .RS 4 +.nf +cargo fix \-\-edition +.fi +.if n .RE +.sp +which behaves the same as \fBcargo check \-\-all\-targets\fP. Similarly if you\(cqd like +to fix code for different platforms you can do: +.sp +.if n .RS 4 +.nf +cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu +.fi +.if n .RE +.sp +or if your crate has optional features: +.sp +.if n .RS 4 +.nf +cargo fix \-\-edition \-\-no\-default\-features \-\-features foo +.fi +.if n .RE +.sp +If you encounter any problems with \fBcargo fix\fP or otherwise have any questions +or feature requests please don\(cqt hesitate to file an issue at +.URL "https://github.com/rust\-lang/cargo" "" "" +.SH "OPTIONS" +.SS "Fix options" +.sp +\fB\-\-broken\-code\fP +.RS 4 +Fix code even if it already has compiler errors. This is useful if \fBcargo +fix\fP fails to apply the changes. It will apply the changes and leave the +broken code in the working directory for you to inspect and manually fix. +.RE +.sp +\fB\-\-edition\fP +.RS 4 +Apply changes that will update the code to the latest edition. This will +not update the edition in the \fBCargo.toml\fP manifest, which must be updated +manually. +.RE +.sp +\fB\-\-edition\-idioms\fP +.RS 4 +Apply suggestions that will update code to the preferred style for the +current edition. +.RE +.sp +\fB\-\-allow\-no\-vcs\fP +.RS 4 +Fix code even if a VCS was not detected. +.RE +.sp +\fB\-\-allow\-dirty\fP +.RS 4 +Fix code even if the working directory has changes. +.RE +.sp +\fB\-\-allow\-staged\fP +.RS 4 +Fix code even if the working directory has staged changes. +.RE +.SS "Package Selection" +.sp +By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (\fB\-\-all\fP is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the \fBworkspace.default\-members\fP key in the root \fBCargo.toml\fP +manifest. +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Fix only the specified packages. See \fBcargo\-pkgid\fP(1) for the +SPEC format. This flag may be specified multiple times. +.RE +.sp +\fB\-\-all\fP +.RS 4 +Fix all members in the workspace. +.RE +.sp +\fB\-\-exclude\fP \fISPEC\fP... +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-all\fP flag. This flag may be specified multiple times. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo fix\fP will fix all targets +(\fB\-\-all\-targets\fP implied). Binaries are skipped if they have +\fBrequired\-features\fP that are missing. +.sp +Passing target selection flags will fix only the +specified targets. +.sp +\fB\-\-lib\fP +.RS 4 +Fix the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Fix the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Fix all binary targets. +.RE +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Fix the specified example. This flag may be specified multiple times. +.RE +.sp +\fB\-\-examples\fP +.RS 4 +Fix all example targets. +.RE +.sp +\fB\-\-test\fP \fINAME\fP... +.RS 4 +Fix the specified integration test. This flag may be specified multiple +times. +.RE +.sp +\fB\-\-tests\fP +.RS 4 +Fix all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting \fBtest = false\fP +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting \fBtest = true\fP in the target settings. +.RE +.sp +\fB\-\-bench\fP \fINAME\fP... +.RS 4 +Fix the specified benchmark. This flag may be specified multiple times. +.RE +.sp +\fB\-\-benches\fP +.RS 4 +Fix all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting \fBbench = +false\fP in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting \fBbench = true\fP in the target +settings. +.RE +.sp +\fB\-\-all\-targets\fP +.RS 4 +Fix all targets. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Fix for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Fix artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.sp +\fB\-\-profile\fP \fINAME\fP +.RS 4 +Changes fix behavior. Currently only \fBtest\fP is +supported, which will fix with the +\fB#[cfg(test)]\fP attribute enabled. This is useful to have it +fix unit tests which are usually excluded via +the \fBcfg\fP attribute. This does not change the actual profile used. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 +No output printed to stdout. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Apply compiler suggestions to the local package: +.sp +.if n .RS 4 +.nf +cargo fix +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Convert a 2015 edition to 2018: +.sp +.if n .RS 4 +.nf +cargo fix \-\-edition +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Apply suggested idioms for the current edition: +.sp +.if n .RS 4 +.nf +cargo fix \-\-edition\-idioms +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-check\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-generate-lockfile.1 b/src/etc/man/cargo-generate-lockfile.1 index 73edd259604..02243c9c152 100644 --- a/src/etc/man/cargo-generate-lockfile.1 +++ b/src/etc/man/cargo-generate-lockfile.1 @@ -1,41 +1,168 @@ -.TH "CARGO\-GENERATE LOCKFILE" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-generate-lockfile \- Generate the lockfile for a package -.SH SYNOPSIS -.PP -\f[I]cargo generate-lockfile\f[] [OPTIONS] -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-manifest-path \f[I]PATH\f[] -Path to the manifest to generate a lockfile for. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-generate-lockfile +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-GENERATE\-LOCKFILE" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-generate\-lockfile \- Generate the lockfile for a package +.SH "SYNOPSIS" +.sp +\fBcargo generate\-lockfile [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +This command will create the \fBCargo.lock\fP lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt if there are any +manifest changes or dependency updates. +.sp +See also \fBcargo\-update\fP(1) which is also capable of creating a \fBCargo.lock\fP +lockfile and has more options for controlling update behavior. +.SH "OPTIONS" +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Create or update the lockfile for the current package or workspace: +.sp +.if n .RS 4 +.nf +cargo generate\-lockfile +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-update\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-help.1 b/src/etc/man/cargo-help.1 new file mode 100644 index 00000000000..e0f47e49420 --- /dev/null +++ b/src/etc/man/cargo-help.1 @@ -0,0 +1,75 @@ +'\" t +.\" Title: cargo-help +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-HELP" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-help \- Get help for a Cargo command +.SH "SYNOPSIS" +.sp +\fBcargo help [\fISUBCOMMAND\fP]\fP +.SH "DESCRIPTION" +.sp +Prints a help message for the given command. +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Get help for a command: +.sp +.if n .RS 4 +.nf +cargo help build +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Help is also available with the \fB\-\-help\fP flag: +.sp +.if n .RS 4 +.nf +cargo build \-\-help +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-init.1 b/src/etc/man/cargo-init.1 index a2b392ad155..6a2fb492614 100644 --- a/src/etc/man/cargo-init.1 +++ b/src/etc/man/cargo-init.1 @@ -1,68 +1,360 @@ -.TH "CARGO\-INIT" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-init \- Create a new cargo package in the current directory -.SH SYNOPSIS -.PP -\f[I]cargo init\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Create a new cargo package in the current directory. -.PP -Use the \f[B]\-\-vcs\f[] option to control the version control system to -use. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-vcs \f[I]VCS\f[] -Initialize a new repository for the given version control system (git or -hg) or do not initialize any version control at all (none) overriding a -global configuration. -.RS -.RE -.TP -.B \-\-bin -Use a binary instead of a library template. -.RS -.RE -.TP -.B \-\-name \f[I]NAME\f[] -Set the resulting package name. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-init +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-INIT" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-init \- Create a new Cargo package in an existing directory +.SH "SYNOPSIS" +.sp +\fBcargo init [\fIOPTIONS\fP] [\fIPATH\fP]\fP +.SH "DESCRIPTION" +.sp +This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory. +.sp +If there are typically\-named Rust source files already in the directory, those +will be used. If not, then a sample \fBsrc/main.rs\fP file will be created, or +\fBsrc/lib.rs\fP if \fB\-\-lib\fP is passed. +.sp +If the directory is not already in a VCS repository, then a new repository +is created (see \fB\-\-vcs\fP below). +.sp +The "authors" field in the manifest is determined from the environment or +configuration settings. A name is required and is determined from (first match +wins): +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBcargo\-new.name\fP Cargo config value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_NAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_AUTHOR_NAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_COMMITTER_NAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBuser.name\fP git configuration value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBUSER\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBUSERNAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBNAME\fP environment variable +.RE +.sp +The email address is optional and is determined from: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBcargo\-new.email\fP Cargo config value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_EMAIL\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_AUTHOR_EMAIL\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_COMMITTER_EMAIL\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBuser.email\fP git configuration value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBEMAIL\fP environment variable +.RE +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" " " +for more information about +configuration files. +.sp +See \fBcargo\-new\fP(1) for a similar command which will create a new package in +a new directory. +.SH "OPTIONS" +.SS "Init Options" +.sp +\fB\-\-bin\fP +.RS 4 +Create a package with a binary target (\fBsrc/main.rs\fP). +This is the default behavior. +.RE +.sp +\fB\-\-lib\fP +.RS 4 +Create a package with a library target (\fBsrc/lib.rs\fP). +.RE +.sp +\fB\-\-edition\fP \fIEDITION\fP +.RS 4 +Specify the Rust edition to use. Default is 2018. +Possible values: 2015, 2018 +.RE +.sp +\fB\-\-name\fP \fINAME\fP +.RS 4 +Set the package name. Defaults to the directory name. +.RE +.sp +\fB\-\-vcs\fP \fIVCS\fP +.RS 4 +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to \fBgit\fP or the configuration value +\fBcargo\-new.vcs\fP, or \fBnone\fP if already inside a VCS repository. +.RE +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. This sets the \fBpublish\fP field which will +restrict publishing only to the given registry name. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. .RE -.SH EXAMPLES -.PP -Initialize a binary cargo package in the current directory -.IP +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Create a binary Cargo package in the current directory: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ init\ \-\-bin -\f[] +cargo init .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-new(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-new\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index f90ad08aa9c..ed0791e7ac8 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -1,161 +1,430 @@ -.TH "CARGO\-INSTALL" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-install \- Install a Rust binary -.SH SYNOPSIS -.PP -\f[I]cargo install\f[] [OPTIONS] -.PP -\f[I]cargo install\f[] [OPTIONS] \-\-list -.SH DESCRIPTION -.PP -Install a Rust binary -.PP -This command manages Cargo\[aq]s local set of install binary crates. -Only packages which have [[bin]] targets can be installed, and all -binaries are installed into the installation root\[aq]s \f[I]bin\f[] -folder. -The installation root is determined, in order of precedence, by -\f[B]\-\-root\f[], \f[I]$CARGO_INSTALL_ROOT\f[], the -\f[I]install.root\f[] configuration key, and finally the home directory -(which is either \f[I]$CARGO_HOME\f[] if set or \f[I]$HOME/.cargo\f[] by -default). -.PP -There are multiple sources from which a crate can be installed. -The default location is crates.io but the \f[B]\-\-git\f[] and -\f[B]\-\-path\f[] flags can change this source. -If the source contains more than one package (such as \f[I]crates.io\f[] -or a git repository with multiple crates) the \f[B]\f[] argument is -required to indicate which crate should be installed. -.PP -Crates from crates.io can optionally specify the version they wish to -install via the \f[B]\-\-vers\f[] 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 \f[B]\-\-bin\f[] argument can -selectively install only one of them, and if you\[aq]d rather install -examples the \f[B]\-\-example\f[] argument can be used as well. -.PP -As a special convenience, omitting the specification entirely -will install the crate in the current directory. -That is, \f[I]install\f[] is equivalent to the more explicit "install -\-\-path .". -.PP -If the source is crates.io or \f[B]\-\-git\f[] 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 \f[B]CARGO_TARGET_DIR\f[] environment variable to a relative path. -In particular, this can be useful for caching build artifacts on continuous integration systems. -.PP -The \f[B]\-\-list\f[] option will list all installed packages (and their -versions). -.SH OPTIONS -.SS Query options -.TP -.B \-\-list -List all installed packages (and their versions). -.RS -.RE -.SS Specifying what crate to install -.TP -.B \-\-vers \f[I]VERS\f[] +'\" t +.\" Title: cargo-install +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-INSTALL" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-install \- Build and install a Rust binary +.SH "SYNOPSIS" +.sp +\fBcargo install [\fIOPTIONS\fP] \fICRATE\fP...\fP +.br +\fBcargo install [\fIOPTIONS\fP] \-\-path \fIPATH\fP\fP +.br +\fBcargo install [\fIOPTIONS\fP] \-\-git \fIURL\fP [\fICRATE\fP...]\fP +.br +\fBcargo install [\fIOPTIONS\fP] \-\-list\fP +.SH "DESCRIPTION" +.sp +This command manages Cargo\(cqs local set of installed binary crates. Only packages +which have \fB[[bin]]\fP targets can be installed, and all binaries are installed into +the installation root\(cqs \fBbin\fP folder. +.sp +The installation root is determined, in order of precedence: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fB\-\-root\fP option +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_INSTALL_ROOT\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBinstall.root\fP Cargo \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_HOME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fB$HOME/.cargo\fP +.RE +.sp +There are multiple sources from which a crate can be installed. The default +location is crates.io but the \fB\-\-git\fP and \fB\-\-path\fP flags can change this +source. If the source contains more than one package (such as crates.io or a +git repository with multiple crates) the \fICRATE\fP argument is required to +indicate which crate should be installed. +.sp +Crates from crates.io can optionally specify the version they wish to install +via the \fB\-\-version\fP flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the \fB\-\-bin\fP argument can selectively install only +one of them, and if you\(cqd rather install examples the \fB\-\-example\fP argument can +be used as well. +.sp +If the source is crates.io or \fB\-\-git\fP then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the \fBCARGO_TARGET_DIR\fP environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems. +.SH "OPTIONS" +.SS "Install Options" +.sp +\fB\-\-vers\fP \fIVERSION\fP, \fB\-\-version\fP \fIVERSION\fP +.RS 4 Specify a version to install from crates.io. -.RS .RE -.TP -.B \-\-git \f[I]URL\f[] +.sp +\fB\-\-git\fP \fIURL\fP +.RS 4 Git URL to install the specified crate from. -.RS .RE -.TP -.B \-\-branch \f[I]BRANCH\f[] +.sp +\fB\-\-branch\fP \fIBRANCH\fP +.RS 4 Branch to use when installing from git. -.RS .RE -.TP -.B \-\-tag \f[I]TAG\f[] +.sp +\fB\-\-tag\fP \fITAG\fP +.RS 4 Tag to use when installing from git. -.RS .RE -.TP -.B \-\-rev \f[I]SHA\f[] +.sp +\fB\-\-rev\fP \fISHA\fP +.RS 4 Specific commit to use when installing from git. -.RS .RE -.TP -.B \-\-path \f[I]PATH\f[] +.sp +\fB\-\-path\fP \fIPATH\fP +.RS 4 Filesystem path to local crate to install. -.RS -.RE -.SS Built and install options -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-j \f[I]N\f[], \-\-jobs \f[I]N\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space\-separated list of features to activate. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-f, \-\-force -Force overwriting existing crates or binaries -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not build the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-debug -Build in debug mode instead of release mode. -.RS .RE -.TP -.B \-\-bin \f[I]NAME\f[] -Only install the binary NAME. -.RS +.sp +\fB\-\-list\fP +.RS 4 +List all installed packages and their versions. +.RE +.sp +\fB\-f\fP, \fB\-\-force\fP +.RS 4 +Force overwriting existing crates or binaries. This can be used to +reinstall or upgrade a crate. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Install only the specified binary. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Install all binaries. .RE -.TP -.B \-\-example \f[I]EXAMPLE\f[] -Install the example EXAMPLE instead of binaries. -.RS +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Install only the specified example. .RE -.TP -.B \-\-root \f[I]DIR\f[] +.sp +\fB\-\-examples\fP +.RS 4 +Install all examples. +.RE +.sp +\fB\-\-root\fP \fIDIR\fP +.RS 4 Directory to install packages into. -.RS .RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Install for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. .RE -.TP -.B \-q, \-\-quiet +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-debug\fP +.RS 4 +Build in debug mode instead of release mode. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-search(1), cargo\-publish(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Install a package from crates.io: +.sp +.if n .RS 4 +.nf +cargo install ripgrep +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Reinstall or upgrade a package: +.sp +.if n .RS 4 +.nf +cargo install ripgrep \-\-force +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-uninstall\fP(1), \fBcargo\-search\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-locate-project.1 b/src/etc/man/cargo-locate-project.1 new file mode 100644 index 00000000000..8402015e2f9 --- /dev/null +++ b/src/etc/man/cargo-locate-project.1 @@ -0,0 +1,155 @@ +'\" t +.\" Title: cargo-locate-project +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-LOCATE\-PROJECT" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-locate\-project \- Print a JSON representation of a Cargo.toml file\(aqs location +.SH "SYNOPSIS" +.sp +\fBcargo locate\-project [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +This command will print a JSON object to stdout with the full path to the +\fBCargo.toml\fP manifest. +.sp +See also \fBcargo\-metadata\fP(1) which is capable of returning the path to a +workspace root. +.SH "OPTIONS" +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 +No output printed to stdout. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Display the path to the manifest based on the current directory: +.sp +.if n .RS 4 +.nf +cargo locate\-project +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-login.1 b/src/etc/man/cargo-login.1 index a82c8284bd1..041c899a88b 100644 --- a/src/etc/man/cargo-login.1 +++ b/src/etc/man/cargo-login.1 @@ -1,41 +1,169 @@ -.TH "CARGO\-LOGIN" "1" "July 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-login +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-LOGIN" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-login \- Save an API token from the registry locally -.SH SYNOPSIS -.PP -\f[I]cargo login\f[] [OPTIONS] [] -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-host \f[I]HOST\f[] -Host to set the token for -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.SH "SYNOPSIS" +.sp +\fBcargo login [\fIOPTIONS\fP] [\fITOKEN\fP]\fP +.SH "DESCRIPTION" +.sp +This command will save the API token to disk so that commands that require +authentication (such as \fBcargo\-publish\fP(1)) will be automatically +authenticated. The token is saved in \fB$CARGO_HOME/credentials\fP. \fBCARGO_HOME\fP +defaults to \fB.cargo\fP in your home directory. +.sp +If the \fITOKEN\fP argument is not specified, it will be read from stdin. +.sp +The API token for crates.io may be retrieved from \c +.URL "https://crates.io/me" "" "." +.sp +Take care to keep the token secret, it should not be shared with anyone else. +.SH "OPTIONS" +.SS "Login Options" +.sp +\fB\-\-host\fP \fIHOST\fP +.RS 4 +Host to set the token for. This option does not affect the behavior of the +login command, and only affects the message displayed. +.RE +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-publish(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Save the API token to disk: +.sp +.if n .RS 4 +.nf +cargo login +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 index deeb632a62c..c21d3593414 100644 --- a/src/etc/man/cargo-metadata.1 +++ b/src/etc/man/cargo-metadata.1 @@ -1,71 +1,417 @@ -.TH "CARGO\-METADATA" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-metadata \- Machine-readable metadata about the current package -.SH SYNOPSIS -.PP -\f[I]cargo metadata\f[] [OPTIONS] -.SH DESCRIPTION -.PP +'\" t +.\" Title: cargo-metadata +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-METADATA" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-metadata \- Machine\-readable metadata about the current package +.SH "SYNOPSIS" +.sp +\fBcargo metadata [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp Output the resolved dependencies of a package, the concrete used versions -including overrides, in machine-readable format. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space-separated list of features. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not include the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-no\-deps -Output information only about the root package and don\[aq]t fetch +including overrides, in JSON to stdout. +.sp +It is recommended to include the \fB\-\-format\-version\fP flag to future\-proof +your code to ensure the output is in the format you are expecting. +.sp +See the \c +.URL "https://crates.io/crates/cargo_metadata" "cargo_metadata crate" +for a Rust API for reading the metadata. +.SH "OUTPUT FORMAT" +.sp +The output has the following format: +.sp +.if n .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\(aqs manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. */ + "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)" + } + ], + /* 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"] + } + ], + /* 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\(aqs 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 + } + } + }, + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe " + ], + /* Array of categories from the manifest. */ + "categories": [ + "command\-line\-utilities" + ], + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust\-lang/cargo", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018" + } + ], + /* 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, with the concrete versions and features + selected. The set depends on the enabled features. + This is null if \-\-no\-deps is specified. + */ + "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. + 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 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" +} +.fi +.if n .RE +.SH "OPTIONS" +.SS "Output Options" +.sp +\fB\-\-no\-deps\fP +.RS 4 +Output information only about the workspace members and don\(cqt fetch dependencies. -.RS .RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the manifest. -.RS +.sp +\fB\-\-format\-version\fP \fIVERSION\fP +.RS 4 +Specify the version of the output format to use. Currently \fB1\fP is the only +possible value. .RE -.TP -.B \-\-format\-version \f[I]VERSION\f[] -Format version [default: 1]. Valid values: 1. -.RS +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. .RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. .RE -.TP -.B \-q, \-\-quiet +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Output JSON about the current package: +.sp +.if n .RS 4 +.nf +cargo metadata \-\-format\-version=1 +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-new.1 b/src/etc/man/cargo-new.1 index 7325c5b2d87..6013f5568ac 100644 --- a/src/etc/man/cargo-new.1 +++ b/src/etc/man/cargo-new.1 @@ -1,68 +1,355 @@ -.TH "CARGO\-NEW" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-new \- Create a new cargo package -.SH SYNOPSIS -.PP -\f[I]cargo new\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Create a new cargo package at . -.PP -Use the \f[B]\-\-vcs\f[] option to control the version control system to -use. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-vcs \f[I]VCS\f[] -Initialize a new repository for the given version control system (git or -hg) or do not initialize any version control at all (none) overriding a -global configuration. -.RS -.RE -.TP -.B \-\-bin -Use a binary instead of a library template. -.RS -.RE -.TP -.B \-\-name \f[I]NAME\f[] -Set the resulting package name. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-new +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-NEW" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-new \- Create a new Cargo package +.SH "SYNOPSIS" +.sp +\fBcargo new [\fIOPTIONS\fP] \fIPATH\fP\fP +.SH "DESCRIPTION" +.sp +This command will create a new Cargo package in the given directory. This +includes a simple template with a \fBCargo.toml\fP manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see \fB\-\-vcs\fP below). +.sp +The "authors" field in the manifest is determined from the environment or +configuration settings. A name is required and is determined from (first match +wins): +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBcargo\-new.name\fP Cargo config value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_NAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_AUTHOR_NAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_COMMITTER_NAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBuser.name\fP git configuration value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBUSER\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBUSERNAME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBNAME\fP environment variable +.RE +.sp +The email address is optional and is determined from: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBcargo\-new.email\fP Cargo config value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_EMAIL\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_AUTHOR_EMAIL\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBGIT_COMMITTER_EMAIL\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBuser.email\fP git configuration value +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBEMAIL\fP environment variable +.RE +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" " " +for more information about +configuration files. +.sp +See \fBcargo\-init\fP(1) for a similar command which will create a new manifest +in an existing directory. +.SH "OPTIONS" +.SS "New Options" +.sp +\fB\-\-bin\fP +.RS 4 +Create a package with a binary target (\fBsrc/main.rs\fP). +This is the default behavior. +.RE +.sp +\fB\-\-lib\fP +.RS 4 +Create a package with a library target (\fBsrc/lib.rs\fP). +.RE +.sp +\fB\-\-edition\fP \fIEDITION\fP +.RS 4 +Specify the Rust edition to use. Default is 2018. +Possible values: 2015, 2018 +.RE +.sp +\fB\-\-name\fP \fINAME\fP +.RS 4 +Set the package name. Defaults to the directory name. +.RE +.sp +\fB\-\-vcs\fP \fIVCS\fP +.RS 4 +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to \fBgit\fP or the configuration value +\fBcargo\-new.vcs\fP, or \fBnone\fP if already inside a VCS repository. +.RE +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. This sets the \fBpublish\fP field which will +restrict publishing only to the given registry name. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. .RE -.SH EXAMPLES -.PP -Create a binary cargo package in the current directory -.IP +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Create a binary Cargo package in the given directory: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ new\ \-\-bin\ ./ -\f[] +cargo new foo .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-init(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-init\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-owner.1 b/src/etc/man/cargo-owner.1 index c690dc0488d..971e53c64f5 100644 --- a/src/etc/man/cargo-owner.1 +++ b/src/etc/man/cargo-owner.1 @@ -1,88 +1,229 @@ -.TH "CARGO\-OWNER" "1" "July 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-owner \- Manage the owners of a crate of the registry -.SH SYNOPSIS -.PP -\f[I]cargo owner\f[] [OPTIONS] [] -.SH DESCRIPTION -.PP -This command will modify the owners for a package on the specified -registry (or default). Note that owners of a package can upload new -versions, and yank old versions. Explicitly named owners can also modify -the set of owners, so take caution! -.PP -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-a, \-\-add \f[I]LOGIN\f[] -Name of a user or team to add as an owner. -.RS -.RE -.TP -.B \-r, \-\-remove \f[I]LOGIN\f[] -Name of a user or team to remove as an owner. -.RS -.RE -.TP -.B \-l, \-\-list +'\" t +.\" Title: cargo-owner +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-OWNER" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-owner \- Manage the owners of a crate on the registry +.SH "SYNOPSIS" +.sp +\fBcargo owner [\fIOPTIONS\fP] \-\-add \fILOGIN\fP [\fICRATE\fP]\fP +.br +\fBcargo owner [\fIOPTIONS\fP] \-\-remove \fILOGIN\fP [\fICRATE\fP]\fP +.br +\fBcargo owner [\fIOPTIONS\fP] \-\-list [\fICRATE\fP]\fP +.SH "DESCRIPTION" +.sp +This command will modify the owners for a crate on the registry. Owners of a +crate can upload new versions and yank old versions. Non\-team owners can also +modify the set of owners, so take care! +.sp +This command requires you to be authenticated with either the \fB\-\-token\fP option +or using \fBcargo\-login\fP(1). +.sp +If the crate name is not specified, it will use the package name from the +current directory. +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html#cargo\-owner" "the reference" " " +for more +information about owners and publishing. +.SH "OPTIONS" +.SS "Owner Options" +.sp +\fB\-a\fP, \fB\-\-add\fP \fILOGIN\fP... +.RS 4 +Add the given user or team as an owner. +.RE +.sp +\fB\-r\fP, \fB\-\-remove\fP \fILOGIN\fP... +.RS 4 +Remove the given user or team as an owner. +.RE +.sp +\fB\-l\fP, \fB\-\-list\fP +.RS 4 List owners of a crate. -.RS .RE -.TP -.B \-\-index \f[I]INDEX\f[] -Registry index to modify owners for. -.RS +.sp +\fB\-\-token\fP \fITOKEN\fP +.RS 4 +API token to use when authenticating. +.RE +.sp +\fB\-\-index\fP \fIINDEX\fP +.RS 4 +The URL of the registry index to use. +.RE +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. .RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." .RE -.TP -.B \-q, \-\-quiet +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." .RE -.SH EXAMPLES -.PP -Add user as an owner of the current package -.IP +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +List owners of a package: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ owner\ \-\-add\ user -\f[] +cargo owner \-\-list foo .fi -.PP -Remove user as an owner of the current package -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Add an owner to a package: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ owner\ \-\-remove\ user -\f[] +cargo owner \-\-add username foo .fi -.PP -Use a certain API token to authenticate with -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Remove an owner from a package: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ owner\ \-\-token\ U6WHXacP3Qqwd5kze1fohr4JEOmGCuRK2 -\f[] +cargo owner \-\-remove username foo .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-publish(1), cargo\-login(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-login\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index f541f512733..23ab981e57a 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -1,59 +1,368 @@ -.TH "CARGO\-PACKAGE" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-package \- Create a distributable tarball -.SH SYNOPSIS -.PP -\f[I]cargo package\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Assemble the local package into a distributable tarball. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-l, \-\-list +'\" t +.\" Title: cargo-package +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-PACKAGE" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-package \- Assemble the local package into a distributable tarball +.SH "SYNOPSIS" +.sp +\fBcargo package [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +This command will create a distributable, compressed \fB.crate\fP file with the +source code of the package in the current directory. The resulting file will +be stored in the \fBtarget/package\fP directory. This performs the following +steps: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Load and check the current workspace, performing some basic checks. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +Path dependencies are not allowed unless they have a version key. Cargo +will ignore the path key for dependencies in published packages. +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Create the compressed \fB.crate\fP file. +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +The original \fBCargo.toml\fP file is rewritten and normalized. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +A \fB.cargo_vcs_info.json\fP file is included that contains information +about the current VCS checkout hash if available (not included with +\fB\-\-allow\-dirty\fP). +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Extract the \fB.crate\fP file and build it to verify it can build. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Check that build scripts did not modify any source files. +.RE +.sp +The list of files included can be controlled with the \fBinclude\fP and \fBexclude\fP +fields in the manifest. +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html" "the reference" " " +for more details about +packaging and publishing. +.SH "OPTIONS" +.SS "Package Options" +.sp +\fB\-l\fP, \fB\-\-list\fP +.RS 4 Print files included in a package without making one. -.RS -.RE -.TP -.B \-\-no\-verify -Don\[aq]t verify the contents by building them. -.RS -.RE -.TP -.B \-\-no\-metadata -Ignore warnings about a lack of human\-usable metadata. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the Cargo.toml to compile. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.RE +.sp +\fB\-\-no\-verify\fP +.RS 4 +Don\(cqt verify the contents by building them. +.RE +.sp +\fB\-\-no\-metadata\fP +.RS 4 +Ignore warnings about a lack of human\-usable metadata (such as the +description or the license). +.RE +.sp +\fB\-\-allow\-dirty\fP +.RS 4 +Allow working directories with uncommitted VCS changes to be packaged. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Package for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-build(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Create a compressed \fB.crate\fP file of the current package: +.sp +.if n .RS 4 +.nf +cargo package +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-pkgid.1 b/src/etc/man/cargo-pkgid.1 index d06da2dde37..322258cf493 100644 --- a/src/etc/man/cargo-pkgid.1 +++ b/src/etc/man/cargo-pkgid.1 @@ -1,75 +1,279 @@ -.TH "CARGO\-PKGID" "1" "July 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-pkgid +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-PKGID" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-pkgid \- Print a fully qualified package specification -.SH SYNOPSIS -.PP -\f[I]cargo pkgid\f[] [OPTIONS] [] -.SH DESCRIPTION -.PP -Given a argument, print out the fully qualified package id -specifier. This command will generate an error if is ambiguous as -to which package it refers to in the dependency graph. If no is -given, then the pkgid for the local package is printed. -.PP -This command requires that a lockfile is available and dependencies have -been fetched. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the manifest to the package to clean. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.SH "SYNOPSIS" +.sp +\fBcargo pkgid [\fIOPTIONS\fP] [\fISPEC\fP]\fP +.SH "DESCRIPTION" +.sp +Given a \fISPEC\fP argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if \fISPEC\fP is ambiguous as to which package it refers to in +the dependency graph. If no \fISPEC\fP is given, then the specifier for the local +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\fP can be one of the +following: +.sp +.it 1 an-trap +.nr an-no-space-flag 1 +.nr an-break-flag 1 +.br +.B Table 1. SPEC Query Format +.TS +allbox tab(:); +lt lt. +T{ +.sp +SPEC Structure +T}:T{ +.sp +Example SPEC +T} +T{ +.sp +\fINAME\fP +T}:T{ +.sp +\fBbitflags\fP +T} +T{ +.sp +\fINAME\fP\fB:\fP\fIVERSION\fP +T}:T{ +.sp +\fBbitflags:1.0.4\fP +T} +T{ +.sp +\fIURL\fP +T}:T{ +.sp +\fB\c +.URL "https://github.com/rust\-lang/cargo" "" "\fP" +T} +T{ +.sp +\fIURL\fP\fB#\fP\fIVERSION\fP +T}:T{ +.sp +\fB\c +.URL "https://github.com/rust\-lang/cargo#0.33.0" "" "\fP" +T} +T{ +.sp +\fIURL\fP\fB#\fP\fINAME\fP +T}:T{ +.sp +\fB\c +.URL "https://github.com/rust\-lang/crates.io\-index#bitflags" "" "\fP" +T} +T{ +.sp +\fIURL\fP\fB#\fP\fINAME\fP\fB:\fP\fIVERSION\fP +T}:T{ +.sp +\fB\c +.URL "https://github.com/rust\-lang/cargo#crates\-io:0.21.0" "" "\fP" +T} +.TE +.sp +.SH "OPTIONS" +.SS "Package Selection" +.sp +\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +.RS 4 +Get the package ID for the given package instead of the current package. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. .RE -.SH EXAMPLES -.PP -Retrieve package specification for foo package -.IP +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Retrieve package specification for \fBfoo\fP package: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ pkgid\ foo -\f[] +cargo pkgid foo .fi -.PP -Retrieve package specification for version 1.0.0 of foo -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Retrieve package specification for version 1.0.0 of \fBfoo\fP: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ pkgid\ foo:1.0.0 -\f[] +cargo pkgid foo:1.0.0 .fi -.PP -Retrieve package specification for foo from crates.io -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Retrieve package specification for \fBfoo\fP from crates.io: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ pkgid\ crates.io/foo -\f[] +cargo pkgid https://github.com/rust\-lang/crates.io\-index#foo .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-generate\-lockfile(1), cargo-search(1), cargo-metadata(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-generate\-lockfile\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index 2f5063139b5..82d32ba62ef 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -1,59 +1,359 @@ -.TH "CARGO\-PUBLISH" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-publish \- Upload a package to the registry. -.SH SYNOPSIS -.PP -\f[I]cargo publish\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Upload a package to the registry. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-host \f[I]HOST\f[] -Host to upload the package to. -.RS -.RE -.TP -.B \-\-token \f[I]TOKEN\f[] -Token to use when uploading. -.RS -.RE -.TP -.B \-\-no\-verify -Don\[aq]t verify package tarball before publish. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the manifest of the package to publish. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-publish +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-PUBLISH" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-publish \- Upload a package to the registry +.SH "SYNOPSIS" +.sp +\fBcargo package [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +This command will create a distributable, compressed \fB.crate\fP file with the +source code of the package in the current directory and upload it to a +registry. The default registry is \c +.URL "https://crates.io" "" "." +This performs the +following steps: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Performs a few checks, including: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +No \fB[patch]\fP sections are allowed in the manifest. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +Checks the \fBpackage.publish\fP key in the manifest for restrictions on which +registries you are allowed to publish to. +.RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Create a \fB.crate\fP file by following the steps in \fBcargo\-package\fP(1). +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Upload the crate to the registry. Note that the server will perform +additional checks on the crate. +.RE +.sp +This command requires you to be authenticated with either the \fB\-\-token\fP option +or using \fBcargo\-login\fP(1). +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html" "the reference" " " +for more details about +packaging and publishing. +.SH "OPTIONS" +.SS "Publish Options" +.sp +\fB\-\-dry\-run\fP +.RS 4 +Perform all checks without uploading. +.RE +.sp +\fB\-\-token\fP \fITOKEN\fP +.RS 4 +API token to use when authenticating. +.RE +.sp +\fB\-\-no\-verify\fP +.RS 4 +Don\(cqt verify the contents by building them. +.RE +.sp +\fB\-\-allow\-dirty\fP +.RS 4 +Allow working directories with uncommitted VCS changes to be packaged. +.RE +.sp +\fB\-\-index\fP \fIINDEX\fP +.RS 4 +The URL of the registry index to use. +.RE +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Publish for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-install(1), cargo\-search(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Publish the current package: +.sp +.if n .RS 4 +.nf +cargo publish +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-package\fP(1), \fBcargo\-login\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 9ad5a1a4b78..0d4d4ec7d6b 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -1,103 +1,416 @@ -.TH "CARGO\-RUN" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-run +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-RUN" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-run \- Run the current package -.SH SYNOPSIS -.PP -\f[I]cargo run\f[] [OPTIONS] [\-\-] [...] -.SH DESCRIPTION -.PP -Run the main binary of the local package (src/main.rs). -.PP -If neither \f[B]\-\-bin\f[] nor \f[B]\-\-example\f[] are given, then if -the package only has one bin target it will be run. -Otherwise \f[B]\-\-bin\f[] specifies the bin target to run, and -\f[B]\-\-example\f[] specifies the example target to run. -At most one of \f[B]\-\-bin\f[] or \f[B]\-\-example\f[] can be provided. -.PP -All of the trailing arguments are passed to the binary to run. -If you\[aq]re passing arguments to both Cargo and the binary, the ones -after \f[B]\-\-\f[] go to the binary, the ones before go to Cargo. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-bin \f[I]NAME\f[] -Name of the bin target to run. -.RS -.RE -.TP -.B \-\-example \f[I]NAME\f[] -Name of the example target to run. -.RS -.RE -.TP -.B \-j \f[I]IN\f[], \-\-jobs \f[I]IN\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-release -Build artifacts in release mode, with optimizations. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space\-separated list of features to also build. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not build the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Build for the target triple. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the Cargo.toml to compile. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.SH "SYNOPSIS" +.sp +\fBcargo run [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +.SH "DESCRIPTION" +.sp +Build the the main binary of the local package (\fBsrc/main.rs\fP) and run it. +.sp +All the arguments following the two dashes (\fB\-\-\fP) are passed to the binary to +run. If you\(cqre passing arguments to both Cargo and the binary, the ones after +\fB\-\-\fP go to the binary, the ones before go to Cargo. +.SH "OPTIONS" +.SS "Package Selection" +.sp +By default, the package in the current working directory is selected. The \fB\-p\fP +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +.RS 4 +The package to run. See \fBcargo\-pkgid\fP(1) for +the SPEC format. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo run\fP will run the binary +target. If there are multiple binary targets, you must pass a target flag to +choose one. +.sp +\fB\-\-bin\fP \fINAME\fP +.RS 4 +Run the specified binary. +.RE +.sp +\fB\-\-example\fP \fINAME\fP +.RS 4 +Run the specified example. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Run for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Run artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. .RE -.SH EXAMPLES -.PP -Run the main binary of the current package -.IP +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Build the local package and run its main target: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ run -\f[] +cargo run .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-new(1), cargo\-init(1), cargo\-build(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Run an example with extra arguments: +.sp +.if n .RS 4 +.nf +cargo run \-\-example exname \-\- \-\-exoption exarg1 exarg2 +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index f5d9a3521a4..9efaf4e245b 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -1,126 +1,481 @@ -.TH "CARGO\-RUSTC" "1" "July 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-rustc \- Compile a package and all of its dependencies -.SH SYNOPSIS -.PP -\f[I]cargo rustc\f[] [OPTIONS] [\-\-] [...] -.SH DESCRIPTION -.PP -.PP -The specified target for the current package (or package specified by -SPEC if provided) will be compiled along with all of its dependencies. -The specified ... -will all be passed to the final compiler invocation, not any of the -dependencies. -Note that the compiler will still unconditionally receive arguments such -as \-L, \-\-extern, and \-\-crate\-type, and the specified ... -will simply be added to the compiler invocation. -.PP -This command requires that only one target is being compiled. -If more than one target is available for the current package the filters -of \-\-lib, \-\-bin, etc, must be used to select which target is -compiled. -To pass flags to all compiler processes spawned by Cargo, use the -$RUSTFLAGS environment variable or the \f[C]build.rustflags\f[] -configuration option. -.PP -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package SPEC\f[] -The profile to compiler for. -.RS -.RE -.TP -.B \-j \f[I]N\f[], \-\-jobs \f[I]N\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-lib -Build only this package\[aq]s library. -.RS -.RE -.TP -.B \-\-bin \f[I]NAME\f[] -Build only the specified binary. -.RS -.RE -.TP -.B \-\-example \f[I]NAME\f[] -Build only the specified example. -.RS -.RE -.TP -.B \-\-test \f[I]NAME\f[] -Build only the specified test target. -.RS -.RE -.TP -.B \-\-bench \f[I]NAME\f[] -Build only the specified benchmark target. -.RS -.RE -.TP -.B \-\-release -Build artifacts in release mode, with optimizations. -.RS -.RE -.TP -.B \-\-profile \f[I]PROFILE -Profile to build the selected target for. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -The version to yank or un\-yank. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not compile default features for the package. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Target triple which compiles will be for. -.RS -.RE -.TP -.B \-\-manifest-path \f[I]PATH\f[] -Path to the manifest to fetch dependencies for. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-rustc +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-RUSTC" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-rustc \- Compile the current package, and pass extra options to the compiler +.SH "SYNOPSIS" +.sp +\fBcargo rustc [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +.SH "DESCRIPTION" +.sp +The specified target for the current package (or package specified by \fB\-p\fP if +provided) will be compiled along with all of its dependencies. The specified +\fIARGS\fP will all be passed to the final compiler invocation, not any of the +dependencies. Note that the compiler will still unconditionally receive +arguments such as \fB\-L\fP, \fB\-\-extern\fP, and \fB\-\-crate\-type\fP, and the specified +\fIARGS\fP will simply be added to the compiler invocation. +.sp +See \c +.URL "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\fP, \fB\-\-bin\fP, etc, must be used to select which +target is compiled. +To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fP +environment variable or the \fBbuild.rustflags\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.SH "OPTIONS" +.SS "Package Selection" +.sp +By default, the package in the current working directory is selected. The \fB\-p\fP +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +.RS 4 +The package to build. See \fBcargo\-pkgid\fP(1) for +the SPEC format. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo rustc\fP will build all +binary and library targets of the selected package. +.sp +Passing target selection flags will build only the +specified targets. +.sp +\fB\-\-lib\fP +.RS 4 +Build the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Build the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Build all binary targets. +.RE +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Build the specified example. This flag may be specified multiple times. +.RE +.sp +\fB\-\-examples\fP +.RS 4 +Build all example targets. +.RE +.sp +\fB\-\-test\fP \fINAME\fP... +.RS 4 +Build the specified integration test. This flag may be specified multiple +times. +.RE +.sp +\fB\-\-tests\fP +.RS 4 +Build all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting \fBtest = false\fP +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting \fBtest = true\fP in the target settings. +.RE +.sp +\fB\-\-bench\fP \fINAME\fP... +.RS 4 +Build the specified benchmark. This flag may be specified multiple times. +.RE +.sp +\fB\-\-benches\fP +.RS 4 +Build all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting \fBbench = +false\fP in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting \fBbench = true\fP in the target +settings. +.RE +.sp +\fB\-\-all\-targets\fP +.RS 4 +Build all targets. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Build for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Build artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-run(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Check if your package (not including dependencies) uses unsafe code: +.sp +.if n .RS 4 +.nf +cargo rustc \-\-lib \-\- \-D unsafe\-code +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Try an experimental flag on the nightly compiler, such as this which prints +the size of every type: +.sp +.if n .RS 4 +.nf +cargo rustc \-\-lib \-\- \-Z print\-type\-sizes +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-build\fP(1), \fBrustc\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 3a898a31a6b..355111c0be7 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -1,124 +1,471 @@ -.TH "CARGO\-RUSTDOC" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-rustdoc \- Build a package\[aq]s documentation, using specified -custom flags. - -.SH SYNOPSIS -.PP -\f[I]cargo rustdoc\f[] [OPTIONS] [\-\-] [...] -.SH DESCRIPTION -.PP -The specified target for the current package (or package specified by -SPEC if provided) will be documented with the specified ... -being passed to the final rustdoc invocation. -Dependencies will not be documented as part of this command. -Note that rustdoc will still unconditionally receive arguments such as -\-L, \-\-extern, and \-\-crate\-type, and the specified ... -will simply be added to the rustdoc invocation. -.PP -If the \-\-package argument is given, then SPEC is a package id -specification which indicates which package should be documented. -If it is not given, then the current package is documented. -For more information on SPEC and its format, see the -\f[C]cargo\ help\ pkgid\f[] command. - -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-open -Open the docs in a browser after the operation. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC\f[] -Package to document. -.RS -.RE -.TP -.B \-j \f[I]N\f[], \-\-jobs \f[I]N\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-lib -Build only this package\[aq]s library. -.RS -.RE -.TP -.B \-\-bin \f[I]NAME\f[] -Build only the specified binary. -.RS -.RE -.TP -.B \-\-example \f[I]NAME\f[] -Build only the specified example. -.RS -.RE -.TP -.B \-\-test \f[I]NAME\f[] -Build only the specified test target. -.RS -.RE -.TP -.B \-\-bench \f[I]NAME\f[] -Build only the specified benchmark target. -.RS -.RE -.TP -.B \-\-release -Build artifacts in release mode, with optimizations. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space-separated list of features to also build. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not build the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Build for the target triple. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the manifest to document. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-rustdoc +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-RUSTDOC" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-rustdoc \- Build a package\(aqs documentation, using specified custom flags +.SH "SYNOPSIS" +.sp +\fBcargo rustdoc [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +.SH "DESCRIPTION" +.sp +The specified target for the current package (or package specified by \fB\-p\fP if +provided) will be documented with the specified \fIARGS\fP being passed to the +final rustdoc invocation. Dependencies will not be documented as part of this +command. Note that rustdoc will still unconditionally receive arguments such +as \fB\-L\fP, \fB\-\-extern\fP, and \fB\-\-crate\-type\fP, and the specified \fIARGS\fP will simply +be added to the rustdoc invocation. +.sp +See \c +.URL "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\fP, \fB\-\-bin\fP, etc, must be used to select which +target is compiled. +To pass flags to all rustdoc processes spawned by Cargo, use the +\fBRUSTDOCFLAGS\fP environment variable or the \fBbuild.rustdocflags\fP configuration +option. +.SH "OPTIONS" +.SS "Documentation Options" +.sp +\fB\-\-open\fP +.RS 4 +Open the docs in a browser after building them. +.RE +.SS "Package Selection" +.sp +By default, the package in the current working directory is selected. The \fB\-p\fP +flag can be used to choose a different package in a workspace. +.sp +\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +.RS 4 +The package to document. See \fBcargo\-pkgid\fP(1) for +the SPEC format. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo rustdoc\fP will document all +binary and library targets of the selected package. The binary will be skipped +if its name is the same as the lib target. Binaries are skipped if they have +\fBrequired\-features\fP that are missing. +.sp +Passing target selection flags will document only the +specified targets. +.sp +\fB\-\-lib\fP +.RS 4 +Document the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Document the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Document all binary targets. +.RE +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Document the specified example. This flag may be specified multiple times. +.RE +.sp +\fB\-\-examples\fP +.RS 4 +Document all example targets. +.RE +.sp +\fB\-\-test\fP \fINAME\fP... +.RS 4 +Document the specified integration test. This flag may be specified multiple +times. +.RE +.sp +\fB\-\-tests\fP +.RS 4 +Document all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting \fBtest = false\fP +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting \fBtest = true\fP in the target settings. +.RE +.sp +\fB\-\-bench\fP \fINAME\fP... +.RS 4 +Document the specified benchmark. This flag may be specified multiple times. +.RE +.sp +\fB\-\-benches\fP +.RS 4 +Document all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting \fBbench = +false\fP in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting \fBbench = true\fP in the target +settings. +.RE +.sp +\fB\-\-all\-targets\fP +.RS 4 +Document all targets. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Document for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Document artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo-doc(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Build documentation with custom CSS included from a given file: +.sp +.if n .RS 4 +.nf +cargo rustdoc \-\-lib \-\- \-\-extend\-css extra.css +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-doc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-search.1 b/src/etc/man/cargo-search.1 index e8b1da3ca9d..f942c8d3a0a 100644 --- a/src/etc/man/cargo-search.1 +++ b/src/etc/man/cargo-search.1 @@ -1,49 +1,167 @@ -.TH "CARGO\-SEARCH" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-search +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-SEARCH" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-search \- Search packages in crates.io -.SH SYNOPSIS -.PP -\f[I]cargo search\f[] [OPTIONS] ... -.SH DESCRIPTION -.PP -Search packages in \f[I]crates.io\f[]. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-host \f[I]HOST\f[] -Host of a registry to search in. -.RS -.RE -.TP -.B \-\-limit \f[I]LIMIT\f[] +.SH "SYNOPSIS" +.sp +\fBcargo search [\fIOPTIONS\fP] [\fIQUERY\fP...]\fP +.SH "DESCRIPTION" +.sp +This performs a textual search for crates on \c +.URL "https://crates.io" "" "." +The matching +crates will be displayed along with their description in TOML format suitable +for copying into a \fBCargo.toml\fP manifest. +.SH "OPTIONS" +.SS "Search Options" +.sp +\fB\-\-limit\fP \fILIMIT\fP +.RS 4 Limit the number of results (default: 10, max: 100). -.RS .RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS +.sp +\fB\-\-index\fP \fIINDEX\fP +.RS 4 +The URL of the registry index to use. .RE -.TP -.B \-q, \-\-quiet +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-install(1), cargo\-publish(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Search for a package from crates.io: +.sp +.if n .RS 4 +.nf +cargo search serde +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-install\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index 45b99e183bd..2505e50851e 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -1,172 +1,636 @@ -.TH "CARGO\-TEST" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-test +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-TEST" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-test \- Execute unit and integration tests of a package -.SH SYNOPSIS -.PP -\f[I]cargo test\f[] [OPTIONS] [\-\-] [...] -.SH DESCRIPTION -.PP -Execute all unit and integration tests of a local package. -.PP -All of the trailing arguments are passed to the test binaries generated -for filtering tests and generally providing options configuring how they -run. -For example, this will run all tests with the name \[aq]foo\[aq] in -their name: -.IP +.SH "SYNOPSIS" +.sp +\fBcargo test [\fIOPTIONS\fP] [TESTNAME] [\-\- \fITEST\-OPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +Compile and execute unit and integration tests. +.sp +The test filtering argument \fBTESTNAME\fP and all the arguments following the two +dashes (\fB\-\-\fP) are passed to the test binaries and thus to \fIlibtest\fP (rustc\(cqs +built in unit\-test and micro\-benchmarking framework). If you\(cqre passing +arguments to both Cargo and the binary, the ones after \fB\-\-\fP go to the binary, +the ones before go to Cargo. For details about libtest\(cqs arguments see the +output of \fBcargo test \(em \-\-help\fP. As an example, this will run all tests with +\fBfoo\fP in their name on 3 threads in parallel: +.sp +.if n .RS 4 .nf -\f[C] -cargo\ test\ foo -\f[] +cargo test foo \-\- \-\-test\-threads 3 .fi -.PP -If the \f[B]\-\-package\f[] argument is given, then \[aq]SPEC\[aq] is a -package id specification which indicates which package should be tested. -If it is not given, then the current package is tested. -For more information on \[aq]SPEC\[aq] and its format, see the "cargo -help pkgid" command. -.PP -The \f[B]\-\-jobs\f[] argument affects the building of the test -executable but does not affect how many jobs are used when running the -tests. -.PP -Compilation can be configured via the \[aq]test\[aq] profile in the +.if n .RE +.sp +Tests are built with the \fB\-\-test\fP option to \fBrustc\fP which creates an +executable with a \fBmain\fP function that automatically runs all functions +annotated with the \fB#[test]\fP attribute in multiple threads. The libtest +harness may be disabled by setting \fBharness = false\fP in the target manifest +settings, in which case your code will need to provide its own \fBmain\fP function +to handle running tests. +.sp +Documentation tests are also run by default, which is handled by \fBrustdoc\fP. It +extracts code samples from documentation comments and executes them. +.SH "OPTIONS" +.SS "Test Options" +.sp +\fB\-\-no\-run\fP +.RS 4 +Compile, but don\(cqt run tests. +.RE +.sp +\fB\-\-no\-fail\-fast\fP +.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" +.sp +By default, when no package selection options are given, the packages selected +depend on the current working directory. In the root of a virtual workspace, +all workspace members are selected (\fB\-\-all\fP is implied). Otherwise, only the +package in the current directory will be selected. The default packages may be +overridden with the \fBworkspace.default\-members\fP key in the root \fBCargo.toml\fP manifest. -.PP -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 \f[B]\-\-nocapture\f[] to the test binaries: -.IP +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Test only the specified packages. See \fBcargo\-pkgid\fP(1) for the +SPEC format. This flag may be specified multiple times. +.RE +.sp +\fB\-\-all\fP +.RS 4 +Test all members in the workspace. +.RE +.sp +\fB\-\-exclude\fP \fISPEC\fP... +.RS 4 +Exclude the specified packages. Must be used in conjunction with the +\fB\-\-all\fP flag. This flag may be specified multiple times. +.RE +.SS "Target Selection" +.sp +When no target selection options are given, \fBcargo test\fP will build the +following targets of the selected packages: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +lib – used to link with binaries, examples, integration tests, and doc tests +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +bins (only if integration tests are built and required features are +available) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +examples – to ensure they compile +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +lib as a unit test +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +bins as unit tests +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +integration tests +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +doc tests for the lib target +.RE +.sp +The default behavior can be changed by setting the \fBtest\fP flag for the target +in the manifest settings. Setting examples to \fBtest = true\fP will build and run +the example as a test. Setting targets to \fBtest = false\fP will stop them from +being tested by default. Target selection options that take a target by name +ignore the \fBtest\fP flag and will always test the given target. +.sp +Doc tests for libraries may be disabled by setting \fBdoctest = false\fP for the +library in the manifest. +.sp +Passing target selection flags will test only the +specified targets. +.sp +\fB\-\-lib\fP +.RS 4 +Test the package\(cqs library. +.RE +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Test the specified binary. This flag may be specified multiple times. +.RE +.sp +\fB\-\-bins\fP +.RS 4 +Test all binary targets. +.RE +.sp +\fB\-\-example\fP \fINAME\fP... +.RS 4 +Test the specified example. This flag may be specified multiple times. +.RE +.sp +\fB\-\-examples\fP +.RS 4 +Test all example targets. +.RE +.sp +\fB\-\-test\fP \fINAME\fP... +.RS 4 +Test the specified integration test. This flag may be specified multiple +times. +.RE +.sp +\fB\-\-tests\fP +.RS 4 +Test all tests. This includes both unit tests for libraries and binaries +and integration tests. Targets may be disabled by setting \fBtest = false\fP +in the manifest settings for the target. Targets (such as examples) may be +explicitly included by setting \fBtest = true\fP in the target settings. +.RE +.sp +\fB\-\-bench\fP \fINAME\fP... +.RS 4 +Test the specified benchmark. This flag may be specified multiple times. +.RE +.sp +\fB\-\-benches\fP +.RS 4 +Test all benchmarks. This includes both unit benchmarks for libraries and +binaries and bench targets. Targets may be disabled by setting \fBbench = +false\fP in the manifest settings for the target. Targets (such as examples) +may be explicitly included by setting \fBbench = true\fP in the target +settings. +.RE +.sp +\fB\-\-all\-targets\fP +.RS 4 +Test all targets. +.RE +.sp +\fB\-\-doc\fP +.RS 4 +Test only the library\(cqs documentation. This cannot be mixed with other +target options. +.RE +.SS "Feature Selection" +.sp +When no feature options are given, the \fBdefault\fP feature is activated for +every selected package. +.sp +\fB\-\-features\fP \fIFEATURES\fP +.RS 4 +Space or comma separated list of features to activate. These features only +apply to the current directory\(cqs package. Features of direct dependencies +may be enabled with \fB/\fP syntax. +.RE +.sp +\fB\-\-all\-features\fP +.RS 4 +Activate all available features of all selected packages. +.RE +.sp +\fB\-\-no\-default\-features\fP +.RS 4 +Do not activate the \fBdefault\fP feature of the current directory\(cqs +package. +.RE +.SS "Compilation Options" +.sp +\fB\-\-target\fP \fITRIPLE\fP +.RS 4 +Test for the given architecture. The default is the host architecture. +.sp +The general format of the triple is \fB\-\-\-\fP where: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBarch\fP = The base CPU architecture, for example \fBx86_64\fP, \fBi686\fP, \fBarm\fP, +\fBthumb\fP, \fBmips\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsub\fP = The CPU sub\-architecture, for example \fBarm\fP has \fBv7\fP, \fBv7s\fP, \fBv5te\fP, +etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBvendor\fP = The vendor, for example \fBunknown\fP, \fBapple\fP, \fBpc\fP, \fBlinux\fP, etc. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBsys\fP = The system name, for example \fBlinux\fP, \fBwindows\fP, etc. \fBnone\fP is +typically used for bare\-metal without an OS. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBabi\fP = The ABI, for example \fBgnu\fP, \fBandroid\fP, \fBeabi\fP, etc. +.RE +.sp +Some parameters may be omitted. Run \fBrustc \-\-print target\-list\fP for a list of +supported targets. +.sp +This may also be specified with the \fBbuild.target\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-release\fP +.RS 4 +Test artifacts in release mode, with optimizations. See the +PROFILES section for details on how this affects profile selection. +.RE +.SS "Output Options" +.sp +\fB\-\-target\-dir\fP \fIDIRECTORY\fP +.RS 4 +Directory for all generated artifacts and intermediate files. May also be +specified with the \fBCARGO_TARGET_DIR\fP environment variable, or the +\fBbuild.target\-dir\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults +to \fBtarget\fP in the root of the workspace. +.RE +.SS "Display Options" +.sp +By default the Rust test harness hides output from test execution to keep +results readable. Test output can be recovered (e.g. for debugging) by passing +\fB\-\-nocapture\fP to the test binaries: +.sp +.if n .RS 4 .nf -\f[C] -cargo\ test\ \-\-\ \-\-nocapture -\f[] +cargo test \-\- \-\-nocapture .fi -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-lib -Test only this package\[aq]s library. -.RS -.RE -.TP -.B \-\-doc -Test only this library\[aq]s documentation -.RS -.RE -.TP -.B \-\-bin \f[I]NAME\f[] -Test only the specified binary. -.RS -.RE -.TP -.B \-\-example \f[I]NAME\f[] -Test only the specified example. -.RS -.RE -.TP -.B \-\-test \f[I]NAME\f[] -Test only the specified integration test target. -.RS -.RE -.TP -.B \-\-bench \f[I]NAME\f[] -Test only the specified benchmark target. -.RS -.RE -.TP -.B \-\-no\-run -Compile, but don\[aq]t run tests. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC ...\f[] -Package to run tests for. -.RS -.RE -.TP -.B \-j \f[I]IN\f[], \-\-jobs \f[I]IN\f[] -Number of parallel jobs, defaults to # of CPUs. -.RS -.RE -.TP -.B \-\-release -Build artifacts in release mode, with optimizations. -.RS -.RE -.TP -.B \-\-features \f[I]FEATURES\f[] -Space\-separated list of features to also build. -.RS -.RE -.TP -.B \-\-all\-features -Build all available features. -.RS -.RE -.TP -.B \-\-no\-default\-features -Do not build the \f[C]default\f[] feature. -.RS -.RE -.TP -.B \-\-target \f[I]TRIPLE\f[] -Build for the target triple. -.RS -.RE -.TP -.B \-\-manifest\-path \f[I]PATH\f[] -Path to the Cargo.toml to compile. -.RS -.RE -.TP -.B \-\-no\-fail\-fast -Run all tests regardless of failure. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +.if n .RE +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-\-message\-format\fP \fIFMT\fP +.RS 4 +The output format for diagnostic messages. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBhuman\fP (default): Display in a human\-readable text format. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBjson\fP: Emit JSON messages to stdout. .RE -.SH EXAMPLES -.PP -Execute all the unit and integration tests of the current package -.IP +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBshort\fP: Emit shorter, human\-readable text messages. +.RE +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SS "Miscellaneous Options" +.sp +The \fB\-\-jobs\fP argument affects the building of the test executable but does not +affect how many threads are used when running the tests. The Rust test harness +includes an option to control the number of threads used: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ test -\f[] +cargo test \-j 2 \-\- \-\-test\-threads=2 .fi -.PP -Execute the BENCH benchmark -.IP +.if n .RE +.sp +\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +.RS 4 +Number of parallel jobs to run. May also be specified with the +\fBbuild.jobs\fP \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Defaults to +the number of CPUs. +.RE +.SH "PROFILES" +.sp +Profiles may be used to configure compiler options such as optimization levels +and debug settings. See +\c +.URL "https://doc.rust\-lang.org/cargo/reference/manifest.html#the\-profile\-sections" "the reference" +for more details. +.sp +Profile selection depends on the target and crate being built. By default the +\fBdev\fP or \fBtest\fP profiles are used. If the \fB\-\-release\fP flag is given, then the +\fBrelease\fP or \fBbench\fP profiles are used. +.TS +allbox tab(:); +lt lt lt. +T{ +.sp +Target +T}:T{ +.sp +Default Profile +T}:T{ +.sp +\fB\-\-release\fP Profile +T} +T{ +.sp +lib, bin, example +T}:T{ +.sp +\fBdev\fP +T}:T{ +.sp +\fBrelease\fP +T} +T{ +.sp +test, bench +T}:T{ +.sp +\fBtest\fP +T}:T{ +.sp +\fBbench\fP +T} +.TE +.sp +.sp +Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +.sp +Unit tests are separate executable artifacts which use the \fBtest\fP/\fBbench\fP +profiles. Example targets are built the same as with \fBcargo build\fP (using the +\fBdev\fP/\fBrelease\fP profiles) unless you are building them with the test harness +(by setting \fBtest = true\fP in the manifest or using the \fB\-\-example\fP flag) in +which case they use the \fBtest\fP/\fBbench\fP profiles. Library targets are built +with the \fBdev\fP/\fBrelease\fP profiles when linked to an integration test, binary, +or doctest. +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Execute all the unit and integration tests of the current package: +.sp +.if n .RS 4 +.nf +cargo test +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Run only a specific test within a specific integration test: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ test\ \-\-bench\ BENCH -\f[] +cargo test \-\-test int_test_name \-\- modname::test_name .fi -.SH SEE ALSO -.PP -cargo(1), cargo\-build(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-bench\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-uninstall.1 b/src/etc/man/cargo-uninstall.1 index 64e9aa7f069..553858d5fc2 100644 --- a/src/etc/man/cargo-uninstall.1 +++ b/src/etc/man/cargo-uninstall.1 @@ -1,56 +1,223 @@ -.TH "CARGO\-UNINSTALL" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-uninstall +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-UNINSTALL" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-uninstall \- Remove a Rust binary -.SH SYNOPSIS -.PP -\f[I]cargo uninstall\f[] [OPTIONS] -.PP -\f[I]cargo uninstall\f[] (\-h | \-\-help) -.SH DESCRIPTION -.PP -The argument SPEC is a package id specification (see -\f[C]cargo\ help\ pkgid\f[]) to specify which crate should be -uninstalled. -By default all binaries are uninstalled for a crate but the -\f[C]\-\-bin\f[] and \f[C]\-\-example\f[] flags can be used to only -uninstall particular binaries. -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-root \f[I]DIR\f[] -Directory to uninstall packages from. -.RS +.SH "SYNOPSIS" +.sp +\fBcargo uninstall [\fIOPTIONS\fP] [\fISPEC\fP...]\fP +.SH "DESCRIPTION" +.sp +This command removes a package installed with \fBcargo\-install\fP(1). The \fISPEC\fP +argument is a package ID specification of the package to remove (see +\fBcargo\-pkgid\fP(1)). +.sp +By default all binaries are removed for a crate but the \fB\-\-bin\fP and +\fB\-\-example\fP flags can be used to only remove particular binaries. +.sp +The installation root is determined, in order of precedence: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fB\-\-root\fP option +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_INSTALL_ROOT\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBinstall.root\fP Cargo \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "" +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBCARGO_HOME\fP environment variable +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fB$HOME/.cargo\fP .RE -.TP -.B \-\-bin \f[I]NAME\f[] -Only uninstall the binary NAME. -.RS +.SH "OPTIONS" +.SS "Install Options" +.sp +\fB\-p\fP, \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Package to uninstall. .RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS +.sp +\fB\-\-bin\fP \fINAME\fP... +.RS 4 +Only uninstall the binary \fINAME\fP. .RE -.TP -.B \-q, \-\-quiet +.sp +\fB\-\-root\fP \fIDIR\fP +.RS 4 +Directory to uninstall packages from. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo-install(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Uninstall a previously installed package. +.sp +.if n .RS 4 +.nf +cargo uninstall ripgrep +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-install\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-update.1 b/src/etc/man/cargo-update.1 index 14b64374d51..f79ab5bec18 100644 --- a/src/etc/man/cargo-update.1 +++ b/src/etc/man/cargo-update.1 @@ -1,80 +1,227 @@ -.TH "CARGO\-UPDATE" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP -cargo\-update \- Update the package dependencies -.SH SYNOPSIS -.PP -\f[I]cargo update\f[] [OPTIONS] -.SH DESCRIPTION -.PP -Update dependencies as recorded in the local lock file. -.PP -This command requires that a \f[I]Cargo.lock\f[] already exists as -generated by \f[I]cargo build\f[] or related commands. -.PP -If \f[I]SPEC\f[] is given, then a conservative update of the -\f[I]lockfile\f[] will be performed. -This means that only the dependency specified by \f[I]SPEC\f[] will be -updated. -Its transitive dependencies will be updated only if \f[I]SPEC\f[] cannot -be updated without updating dependencies. -All other dependencies will remain locked at their currently recorded -versions. -.PP -If \f[I]PRECISE\f[] is specified, then \f[B]\-\-aggressive\f[] must not -also be specified. -The argument \f[I]PRECISE\f[] is a string representing a precise -revision that the package being updated should be updated to. -For example, if the package comes from a git repository, then -\f[I]PRECISE\f[] would be the exact revision that the repository should -be updated to. -.PP -If \f[I]SPEC\f[] is not given, then all dependencies will be -re\-resolved and updated. -.PP -For more information about package id specifications, see "cargo help -pkgid". -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-p \f[I]SPEC\f[], \-\-package \f[I]SPEC ...\f[] -Package to update. -.RS -.RE -.TP -.B \-\-aggressive -Force updating all dependencies of as well. -.RS -.RE -.TP -.B \-\-precise \f[I]PRECISE\f[] -Update a single dependency to exactly \f[I]PRECISE\f[]. -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-q, \-\-quiet +'\" t +.\" Title: cargo-update +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-UPDATE" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-update \- Update dependencies as recorded in the local lock file +.SH "SYNOPSIS" +.sp +\fBcargo update [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +This command will update dependencies in the \fBCargo.lock\fP file to the latest +version. It requires that the \fBCargo.lock\fP file already exists as generated +by commands such as \fBcargo\-build\fP(1) or \fBcargo\-generate\-lockfile\fP(1). +.SH "OPTIONS" +.SS "Update Options" +.sp +\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +.RS 4 +Update only the specified packages. This flag may be specified +multiple times. See \fBcargo\-pkgid\fP(1) for the SPEC format. +.sp +If packages are specified with the \fB\-p\fP flag, then a conservative update of +the lockfile will be performed. This means that only the dependency specified +by SPEC will be updated. Its transitive dependencies will be updated only if +SPEC cannot be updated without updating dependencies. All other dependencies +will remain locked at their currently recorded versions. +.sp +If \fB\-p\fP is not specified, all dependencies are updated. +.RE +.sp +\fB\-\-aggressive\fP +.RS 4 +When used with \fB\-p\fP, dependencies of \fISPEC\fP are forced to update as well. +Cannot be used with \fB\-\-precise\fP. +.RE +.sp +\fB\-\-precise\fP \fIPRECISE\fP +.RS 4 +When used with \fB\-p\fP, allows you to specify a specific version number to +set the package to. If the package comes from a git repository, this can +be a git revision (such as a SHA hash or tag). +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Update all dependencies in the lockfile: +.sp +.if n .RS 4 +.nf +cargo update +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Update only specific dependencies: +.sp +.if n .RS 4 +.nf +cargo update \-p foo \-p bar +.fi +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Set a specific dependency to a specific version: +.sp +.if n .RS 4 +.nf +cargo update \-p foo \-\-precise 1.2.3 +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-generate\-lockfile\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-verify-project.1 b/src/etc/man/cargo-verify-project.1 new file mode 100644 index 00000000000..e95a86e0cc2 --- /dev/null +++ b/src/etc/man/cargo-verify-project.1 @@ -0,0 +1,178 @@ +'\" t +.\" Title: cargo-verify-project +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-VERIFY\-PROJECT" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" +cargo\-verify\-project \- Check correctness of crate manifest +.SH "SYNOPSIS" +.sp +\fBcargo verify\-project [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +This command will parse the local manifest and check its validity. It emits a +JSON object with the result. A successful validation will display: +.sp +.if n .RS 4 +.nf +{"success":"true"} +.fi +.if n .RE +.sp +An invalid workspace will display: +.sp +.if n .RS 4 +.nf +{"invalid":"human\-readable error message"} +.fi +.if n .RE +.SH "OPTIONS" +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 +No output printed to stdout. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-manifest\-path\fP \fIPATH\fP +.RS 4 +Path to the \fBCargo.toml\fP file. By default, Cargo searches in the current +directory or any parent directory for the \fBCargo.toml\fP file. +.RE +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +The workspace is OK. +.RE +.sp +1 +.RS 4 +The workspace is invalid. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Check the current workspace for errors: +.sp +.if n .RS 4 +.nf +cargo verify\-project +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-package\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-version.1 b/src/etc/man/cargo-version.1 index c78344d3fb3..9c74cf20c59 100644 --- a/src/etc/man/cargo-version.1 +++ b/src/etc/man/cargo-version.1 @@ -1,31 +1,99 @@ -.TH "CARGO\-VERSION" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-version +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-VERSION" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-version \- Show version information -.SH SYNOPSIS -.PP -\f[I]cargo version\f[] [OPTIONS] -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS +.SH "SYNOPSIS" +.sp +\fBcargo version [\fIOPTIONS\fP]\fP +.SH "DESCRIPTION" +.sp +Displays the version of Cargo. +.SH "OPTIONS" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Display additional version information. .RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Display the version: +.sp +.if n .RS 4 +.nf +cargo version +.fi +.if n .RE .RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +The version is also available via flags: +.sp +.if n .RS 4 +.nf +cargo \-\-version +cargo \-V +.fi +.if n .RE .RE -.SH SEE ALSO -.PP -cargo(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Display extra version information: +.sp +.if n .RS 4 +.nf +cargo \-Vv +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1 index f54b2bd6b5b..df48005fc35 100644 --- a/src/etc/man/cargo-yank.1 +++ b/src/etc/man/cargo-yank.1 @@ -1,68 +1,185 @@ -.TH "CARGO\-YANK" "1" "July 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo-yank +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO\-YANK" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo\-yank \- Remove a pushed crate from the index -.SH SYNOPSIS -.PP -\f[I]cargo yank\f[] [OPTIONS] [] -.SH DESCRIPTION -.PP -The yank command removes a previously pushed crate\[aq]s version from -the server\[aq]s index. -This command does not delete any data, and the crate will still be -available for download via the registry\[aq]s download link. -.PP -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. -.PP -.SH OPTIONS -.TP -.B \-h, \-\-help -Print this message. -.RS -.RE -.TP -.B \-\-vers \f[I]VERSION\f[] -The version to yank or un-yank. -.RS -.RE -.TP -.B \-\-undo -Undo a yank, putting a version back into the index. -.RS +.SH "SYNOPSIS" +.sp +\fBcargo yank [\fIOPTIONS\fP] \-\-vers \fIVERSION\fP [\fICRATE\fP]\fP +.SH "DESCRIPTION" +.sp +The yank command removes a previously published crate\(cqs version from the +server\(cqs index. This command does not delete any data, and the crate will +still be available for download via the registry\(cqs download link. +.sp +Note that existing crates locked to a yanked version will still be able to +download the yanked version to use it. Cargo will, however, not allow any new +crates to be locked to any yanked version. +.sp +This command requires you to be authenticated with either the \fB\-\-token\fP option +or using \fBcargo\-login\fP(1). +.sp +If the crate name is not specified, it will use the package name from the +current directory. +.SH "OPTIONS" +.SS "Owner Options" +.sp +\fB\-\-vers\fP \fIVERSION\fP +.RS 4 +The version to yank or un\-yank. .RE -.TP -.B \-\-index \f[I]INDEX\f[] -Registry index to yank from. -.RS +.sp +\fB\-\-undo\fP +.RS 4 +Undo a yank, putting a version back into the index. .RE -.TP -.B \-\-token \f[I]TOKEN\f[] +.sp +\fB\-\-token\fP \fITOKEN\fP +.RS 4 API token to use when authenticating. -.RS .RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS +.sp +\fB\-\-index\fP \fIINDEX\fP +.RS 4 +The URL of the registry index to use. +.RE +.sp +\fB\-\-registry\fP \fIREGISTRY\fP +.RS 4 +Alternative registry to use. +.sp +This option is unstable and available only on the nightly channel and requires +the \fB\-Z unstable\-options\fP flag to enable. +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." .RE -.TP -.B \-q, \-\-quiet +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 No output printed to stdout. -.RS -.RE -.TP -.B \-\-color \f[I]WHEN\f[] -Coloring: auto, always, never. -.RS -.RE -.SH SEE ALSO -.PP -cargo(1), cargo\-owner(1), cargo\-version(1) -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Yank a crate from the index: +.sp +.if n .RS 4 +.nf +cargo yank \-\-vers 1.0.7 foo +.fi +.if n .RE +.RE +.SH "SEE ALSO" +.sp +\fBcargo\fP(1), \fBcargo\-login\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 index b70b69a2b0c..e36f89393fb 100644 --- a/src/etc/man/cargo.1 +++ b/src/etc/man/cargo.1 @@ -1,206 +1,473 @@ -.TH "CARGO" "1" "May 2016" "The Rust package manager" "Cargo Manual" -.hy -.SH NAME -.PP +'\" t +.\" Title: cargo +.\" Author: [see the "AUTHOR(S)" section] +.\" Generator: Asciidoctor 1.5.8 +.\" Date: 2018-12-08 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "CARGO" "1" "2018-12-08" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\fI\\$2\fP <\\$1>\\$3 +.. +.als MTO URL +.if \n[.g] \{\ +. mso www.tmac +. am URL +. ad l +. . +. am MTO +. ad l +. . +. LINKSTYLE blue R < > +.\} +.SH "NAME" cargo \- The Rust package manager -.SH SYNOPSIS -.PP -\f[I]cargo\f[] [...] -.SH DESCRIPTION -.PP -This program is a package manager for the Rust language, available at -. -.SH OPTIONS -.TP -.B \-h, \-\-help -Display a help message. -.RS -.RE -.TP -.B \-V, \-\-version -Print version information and exit. -.RS -.RE -.TP -.B \-\-list -List all available cargo commands. -.RS -.RE -.TP -.B \-\-explain CODE -Run \f[C]rustc\ \-\-explain\ CODE\f[] -.RS -.RE -.TP -.B \-v, \-\-verbose -Use verbose output. -.RS -.RE -.TP -.B \-\-color -Configure coloring of output. -.RS -.RE -.SH COMMANDS -.PP -To get extended information about commands, run \f[I]cargo help -\f[] or \f[I]man cargo\-command\f[] -.TP -.B cargo\-build(1) -Compile the current package. -.RS -.RE -.TP -.B cargo\-clean(1) -Remove the target directory with build output. -.RS -.RE -.TP -.B cargo\-doc(1) -Build this package\[aq]s and its dependencies\[aq] documentation. -.RS -.RE -.TP -.B cargo\-init(1) -Create a new cargo package in the current directory. -.RS -.RE -.TP -.B cargo\-install(1) -Install a Rust binary. -.RS -.RE -.TP -.B cargo\-new(1) -Create a new cargo package. -.RS -.RE -.TP -.B cargo\-run(1) -Build and execute src/main.rs. -.RS -.RE -.TP -.B cargo\-test(1) -Run the tests for the package. -.RS -.RE -.TP -.B cargo\-bench(1) -Run the benchmarks for the package. -.RS -.RE -.TP -.B cargo\-update(1) -Update dependencies in Cargo.lock. -.RS -.RE -.TP -.B cargo\-rustc(1) -Compile the current package, and optionally pass additional rustc parameters -.RS -.RE -.TP -.B cargo\-package(1) -Generate a source tarball for the current package. -.RS -.RE -.TP -.B cargo\-publish(1) -Package and upload this package to the registry. -.RS -.RE -.TP -.B cargo\-owner(1) -Manage the owners of a crate on the registry. -.RS +.SH "SYNOPSIS" +.sp +\fBcargo [\fIOPTIONS\fP] \fICOMMAND\fP [\fIARGS\fP]\fP +.br +\fBcargo [\fIOPTIONS\fP] \-\-version\fP +.br +\fBcargo [\fIOPTIONS\fP] \-\-list\fP +.br +\fBcargo [\fIOPTIONS\fP] \-\-help\fP +.br +\fBcargo [\fIOPTIONS\fP] \-\-explain \fICODE\fP\fP +.SH "DESCRIPTION" +.sp +This program is a package manager and build tool for the Rust language, +available at \c +.URL "http://rust\-lang.org" "" "." +.SH "COMMANDS" +.SS "Build Commands" +.sp +\fBcargo\-bench\fP(1) +.RS 4 +Execute benchmarks of a package. +.RE +.sp +\fBcargo\-build\fP(1) +.RS 4 +Compile a package. +.RE +.sp +\fBcargo\-check\fP(1) +.RS 4 +Check a local package and all of its dependencies for errors. +.RE +.sp +\fBcargo\-clean\fP(1) +.RS 4 +Remove artifacts that Cargo has generated in the past. +.RE +.sp +\fBcargo\-doc\fP(1) +.RS 4 +Build a package\(cqs documentation. +.RE +.sp +\fBcargo\-fetch\fP(1) +.RS 4 +Fetch dependencies of a package from the network. +.RE +.sp +\fBcargo\-fix\fP(1) +.RS 4 +Automatically fix lint warnings reported by rustc. +.RE +.sp +\fBcargo\-run\fP(1) +.RS 4 +Run a binary of the local package. +.RE +.sp +\fBcargo\-rustc\fP(1) +.RS 4 +Compile a package, and pass extra options to the compiler. +.RE +.sp +\fBcargo\-rustdoc\fP(1) +.RS 4 +Build a package\(cqs documentation, using specified custom flags. +.RE +.sp +\fBcargo\-test\fP(1) +.RS 4 +Execute unit and integration tests of a package. +.RE +.SS "Manifest Commands" +.sp +\fBcargo\-generate\-lockfile\fP(1) +.RS 4 +Generate \fBCargo.lock\fP for a project. +.RE +.sp +\fBcargo\-locate\-project\fP(1) +.RS 4 +Print a JSON representation of a \fBCargo.toml\fP file\(cqs location. +.RE +.sp +\fBcargo\-metadata\fP(1) +.RS 4 +Output the resolved dependencies of a package, the concrete used versions +including overrides, in machine\-readable format. .RE -.TP -.B cargo\-uninstall(1) +.sp +\fBcargo\-pkgid\fP(1) +.RS 4 +Print a fully qualified package specification. +.RE +.sp +\fBcargo\-update\fP(1) +.RS 4 +Update dependencies as recorded in the local lock file. +.RE +.sp +\fBcargo\-verify\-project\fP(1) +.RS 4 +Check correctness of crate manifest. +.RE +.SS "Package Commands" +.sp +\fBcargo\-init\fP(1) +.RS 4 +Create a new Cargo package in an existing directory. +.RE +.sp +\fBcargo\-install\fP(1) +.RS 4 +Build and install a Rust binary. +.RE +.sp +\fBcargo\-new\fP(1) +.RS 4 +Create a new Cargo package. +.RE +.sp +\fBcargo\-search\fP(1) +.RS 4 +Search packages in crates.io. +.RE +.sp +\fBcargo\-uninstall\fP(1) +.RS 4 Remove a Rust binary. -.RS -.RE -.TP -.B cargo\-search(1) -Search registry for crates. -.RS -.RE -.TP -.B cargo\-help(1) -Display help for a cargo command -.RS -.RE -.TP -.B cargo\-version(1) -Print cargo\[aq]s version and exit. -.RS -.RE -.SH FILES -.TP -.B ~/.cargo -Directory in which Cargo stores repository data. -Cargo can be instructed to use a \f[I]\&.cargo\f[] subdirectory in a -different location by setting the \f[B]CARGO_HOME\f[] environment +.RE +.SS "Publishing Commands" +.sp +\fBcargo\-login\fP(1) +.RS 4 +Save an API token from the registry locally. +.RE +.sp +\fBcargo\-owner\fP(1) +.RS 4 +Manage the owners of a crate on the registry. +.RE +.sp +\fBcargo\-package\fP(1) +.RS 4 +Assemble the local package into a distributable tarball. +.RE +.sp +\fBcargo\-publish\fP(1) +.RS 4 +Upload a package to the registry. +.RE +.sp +\fBcargo\-yank\fP(1) +.RS 4 +Remove a pushed crate from the index. +.RE +.SS "General Commands" +.sp +\fBcargo\-help\fP(1) +.RS 4 +Display help information about Cargo. +.RE +.sp +\fBcargo\-version\fP(1) +.RS 4 +Show version information. +.RE +.SH "OPTIONS" +.SS "Special Options" +.sp +\fB\-V\fP, \fB\-\-version\fP +.RS 4 +Print version info and exit. If used with \fB\-\-verbose\fP, prints extra +information. +.RE +.sp +\fB\-\-list\fP +.RS 4 +List all installed Cargo subcommands. If used with \fB\-\-verbose\fP, prints +extra information. +.RE +.sp +\fB\-\-explain \fICODE\fP\fP +.RS 4 +Run \fBrustc \-\-explain CODE\fP which will print out a detailed explanation of +an error message (for example, \fBE0004\fP). +.RE +.SS "Display Options" +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the \fBterm.verbose\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 +No output printed to stdout. +.RE +.sp +\fB\-\-color\fP \fIWHEN\fP +.RS 4 +Control when colored output is used. Valid values: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBauto\fP (default): Automatically detect if color support is available on the +terminal. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBalways\fP: Always display colors. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +. sp -1 +. IP \(bu 2.3 +.\} +\fBnever\fP: Never display colors. +.RE +.sp +May also be specified with the \fBterm.color\fP +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.RE +.SS "Manifest Options" +.sp +\fB\-\-frozen\fP, \fB\-\-locked\fP +.RS 4 +Either of these flags requires that the \fBCargo.lock\fP file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.SS "Common Options" +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Prints help information. +.RE +.sp +\fB\-Z\fP \fIFLAG\fP... +.RS 4 +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for +details. +.RE +.SH "ENVIRONMENT" +.sp +See \c +.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " +for +details on environment variables that Cargo reads. +.SH "EXIT STATUS" +.sp +0 +.RS 4 +Cargo succeeded. +.RE +.sp +101 +.RS 4 +Cargo failed to complete. +.RE +.SH "FILES" +.sp +\fB~/.cargo/\fP +.RS 4 +Default location for Cargo\(cqs "home" directory where it stores various +files. The location can be changed with the \fBCARGO_HOME\fP environment variable. -.RS .RE -.SH EXAMPLES -.PP -Build a local package and all of its dependencies -.IP +.sp +\fB$CARGO_HOME/bin/\fP +.RS 4 +Binaries installed by \fBcargo\-install\fP(1) will be located here. If using +rustup, executables distributed with Rust are also located here. +.RE +.sp +\fB$CARGO_HOME/config\fP +.RS 4 +The global configuration file. See \c +.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" +for more information about configuration files. +.RE +.sp +\fB.cargo/config\fP +.RS 4 +Cargo automatically searches for a file named \fB.cargo/config\fP in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file. +.RE +.sp +\fB$CARGO_HOME/credentials\fP +.RS 4 +Private authentication information for logging in to a registry. +.RE +.sp +\fB$CARGO_HOME/registry/\fP +.RS 4 +This directory contains cached downloads of the registry index and any +downloaded dependencies. +.RE +.sp +\fB$CARGO_HOME/git/\fP +.RS 4 +This directory contains cached downloads of git dependencies. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 1." 4.2 +.\} +Build a local package and all of its dependencies: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ build -\f[] +cargo build .fi -.PP -Build a package with optimizations -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 2." 4.2 +.\} +Build a package with optimizations: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ build\ \-\-release -\f[] +cargo build \-\-release .fi -.PP -Run tests for a cross\-compiled target -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 3." 4.2 +.\} +Run tests for a cross\-compiled target: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ test\ \-\-target\ i686\-unknown\-linux\-gnu -\f[] +cargo test \-\-target i686\-unknown\-linux\-gnu .fi -.PP -Create a new package that builds an executable -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 4.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 4." 4.2 +.\} +Create a new package that builds an executable: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ new\ \-\-bin\ foobar -\f[] +cargo new foobar .fi -.PP -Create a package in the current directory -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 5.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 5." 4.2 +.\} +Create a package in the current directory: +.sp +.if n .RS 4 .nf -\f[C] -$\ mkdir\ foo\ &&\ cd\ foo -$\ cargo\ init\ . -\f[] +mkdir foo && cd foo +cargo init . .fi -.PP -Learn about a command\[aq]s options and usage -.IP +.if n .RE +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 6.\h'+01'\c +.\} +.el \{\ +. sp -1 +. IP " 6." 4.2 +.\} +Learn about a command\(cqs options and usage: +.sp +.if n .RS 4 .nf -\f[C] -$\ cargo\ help\ clean -\f[] +cargo help clean .fi -.SH SEE ALSO -.PP -rustc(1), rustdoc(1) -.SH BUGS -.PP -See for issues. -.SH COPYRIGHT -.PP -This work is dual\-licensed under Apache 2.0 and MIT terms. -See \f[I]COPYRIGHT\f[] file in the cargo source distribution. +.if n .RE +.RE +.SH "BUGS" +.sp +See \c +.URL "https://github.com/rust\-lang/cargo/issues" "" " " +for issues. +.SH "SEE ALSO" +.sp +\fBrustc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file