From 8b878f38cda7bc771568162cac344fe8aa9003b2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 1 Aug 2020 09:13:07 -0700 Subject: [PATCH 1/7] Add mdman for generating man pages. --- crates/mdman/Cargo.lock | 449 +++++++++++++ crates/mdman/Cargo.toml | 18 + crates/mdman/README.md | 7 + crates/mdman/build-man.sh | 7 + crates/mdman/doc/mdman.md | 95 +++ crates/mdman/doc/out/mdman.1 | 124 ++++ crates/mdman/doc/out/mdman.md | 95 +++ crates/mdman/doc/out/mdman.txt | 91 +++ crates/mdman/src/format.rs | 20 + crates/mdman/src/format/man.rs | 430 +++++++++++++ crates/mdman/src/format/md.rs | 114 ++++ crates/mdman/src/format/text.rs | 605 ++++++++++++++++++ crates/mdman/src/hbs.rs | 217 +++++++ crates/mdman/src/lib.rs | 118 ++++ crates/mdman/src/main.rs | 133 ++++ crates/mdman/src/util.rs | 44 ++ crates/mdman/tests/compare.rs | 46 ++ .../mdman/tests/compare/expected/formatting.1 | 118 ++++ .../tests/compare/expected/formatting.md | 94 +++ .../tests/compare/expected/formatting.txt | 84 +++ crates/mdman/tests/compare/expected/links.1 | 31 + crates/mdman/tests/compare/expected/links.md | 35 + crates/mdman/tests/compare/expected/links.txt | 30 + crates/mdman/tests/compare/expected/options.1 | 94 +++ .../mdman/tests/compare/expected/options.md | 77 +++ .../mdman/tests/compare/expected/options.txt | 57 ++ crates/mdman/tests/compare/expected/tables.1 | 108 ++++ crates/mdman/tests/compare/expected/tables.md | 35 + .../mdman/tests/compare/expected/tables.txt | 45 ++ crates/mdman/tests/compare/expected/vars.7 | 9 + crates/mdman/tests/compare/expected/vars.md | 7 + crates/mdman/tests/compare/expected/vars.txt | 6 + crates/mdman/tests/compare/formatting.md | 94 +++ .../tests/compare/includes/options-common.md | 14 + crates/mdman/tests/compare/links.md | 35 + crates/mdman/tests/compare/options.md | 62 ++ crates/mdman/tests/compare/tables.md | 35 + crates/mdman/tests/compare/vars.md | 7 + crates/mdman/tests/invalid.rs | 34 + crates/mdman/tests/invalid/nested.md | 6 + .../mdman/tests/invalid/not-inside-options.md | 5 + 41 files changed, 3735 insertions(+) create mode 100644 crates/mdman/Cargo.lock create mode 100644 crates/mdman/Cargo.toml create mode 100644 crates/mdman/README.md create mode 100755 crates/mdman/build-man.sh create mode 100644 crates/mdman/doc/mdman.md create mode 100644 crates/mdman/doc/out/mdman.1 create mode 100644 crates/mdman/doc/out/mdman.md create mode 100644 crates/mdman/doc/out/mdman.txt create mode 100644 crates/mdman/src/format.rs create mode 100644 crates/mdman/src/format/man.rs create mode 100644 crates/mdman/src/format/md.rs create mode 100644 crates/mdman/src/format/text.rs create mode 100644 crates/mdman/src/hbs.rs create mode 100644 crates/mdman/src/lib.rs create mode 100644 crates/mdman/src/main.rs create mode 100644 crates/mdman/src/util.rs create mode 100644 crates/mdman/tests/compare.rs create mode 100644 crates/mdman/tests/compare/expected/formatting.1 create mode 100644 crates/mdman/tests/compare/expected/formatting.md create mode 100644 crates/mdman/tests/compare/expected/formatting.txt create mode 100644 crates/mdman/tests/compare/expected/links.1 create mode 100644 crates/mdman/tests/compare/expected/links.md create mode 100644 crates/mdman/tests/compare/expected/links.txt create mode 100644 crates/mdman/tests/compare/expected/options.1 create mode 100644 crates/mdman/tests/compare/expected/options.md create mode 100644 crates/mdman/tests/compare/expected/options.txt create mode 100644 crates/mdman/tests/compare/expected/tables.1 create mode 100644 crates/mdman/tests/compare/expected/tables.md create mode 100644 crates/mdman/tests/compare/expected/tables.txt create mode 100644 crates/mdman/tests/compare/expected/vars.7 create mode 100644 crates/mdman/tests/compare/expected/vars.md create mode 100644 crates/mdman/tests/compare/expected/vars.txt create mode 100644 crates/mdman/tests/compare/formatting.md create mode 100644 crates/mdman/tests/compare/includes/options-common.md create mode 100644 crates/mdman/tests/compare/links.md create mode 100644 crates/mdman/tests/compare/options.md create mode 100644 crates/mdman/tests/compare/tables.md create mode 100644 crates/mdman/tests/compare/vars.md create mode 100644 crates/mdman/tests/invalid.rs create mode 100644 crates/mdman/tests/invalid/nested.md create mode 100644 crates/mdman/tests/invalid/not-inside-options.md diff --git a/crates/mdman/Cargo.lock b/crates/mdman/Cargo.lock new file mode 100644 index 00000000000..124750d9d51 --- /dev/null +++ b/crates/mdman/Cargo.lock @@ -0,0 +1,449 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +[[package]] +name = "ansi_term" +version = "0.11.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee49baf6cb617b853aa8d93bf420db2383fab46d314482ca2803b40d5fde979b" +dependencies = [ + "winapi", +] + +[[package]] +name = "anyhow" +version = "1.0.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b602bfe940d21c130f3895acd65221e8a61270debe89d628b9cb4e3ccb8569b" + +[[package]] +name = "bitflags" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf1de2fe8c75bc145a2f577add951f8134889b4795d47466a54a5c846d691693" + +[[package]] +name = "block-buffer" +version = "0.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0940dc441f31689269e10ac70eb1002a3a1d3ad1390e030043662eb7fe4688b" +dependencies = [ + "block-padding", + "byte-tools", + "byteorder", + "generic-array", +] + +[[package]] +name = "block-padding" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fa79dedbb091f449f1f39e53edf88d5dbe95f895dae6135a8d7b881fb5af73f5" +dependencies = [ + "byte-tools", +] + +[[package]] +name = "byte-tools" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3b5ca7a04898ad4bcd41c90c5285445ff5b791899bb1b0abdd2a2aa791211d7" + +[[package]] +name = "byteorder" +version = "1.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "08c48aae112d48ed9f069b33538ea9e3e90aa263cfa3d1c24309612b1f7472de" + +[[package]] +name = "cfg-if" +version = "0.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4785bdd1c96b2a846b2bd7cc02e86b6b3dbf14e7e53446c4f54c92a361040822" + +[[package]] +name = "ctor" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39858aa5bac06462d4dd4b9164848eb81ffc4aa5c479746393598fd193afa227" +dependencies = [ + "quote", + "syn", +] + +[[package]] +name = "difference" +version = "2.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "524cbf6897b527295dff137cec09ecf3a05f4fddffd7dfcd1585403449e74198" + +[[package]] +name = "digest" +version = "0.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f3d0c8c8752312f9713efd397ff63acb9f85585afbf179282e720e7704954dd5" +dependencies = [ + "generic-array", +] + +[[package]] +name = "fake-simd" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e88a8acf291dafb59c2d96e8f59828f3838bb1a70398823ade51a84de6a6deed" + +[[package]] +name = "generic-array" +version = "0.12.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c68f0274ae0e023facc3c97b2e00f076be70e254bc851d972503b328db79b2ec" +dependencies = [ + "typenum", +] + +[[package]] +name = "handlebars" +version = "3.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86dbc8a0746b08f363d2e00da48e6c9ceb75c198ac692d2715fcbb5bee74c87d" +dependencies = [ + "log", + "pest", + "pest_derive", + "quick-error", + "serde", + "serde_json", + "walkdir", +] + +[[package]] +name = "idna" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02e2673c30ee86b5b96a9cb52ad15718aa1f966f5ab9ad54a8b95d5ca33120a9" +dependencies = [ + "matches", + "unicode-bidi", + "unicode-normalization", +] + +[[package]] +name = "itoa" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc6f3ad7b9d11a0c00842ff8de1b60ee58661048eb8049ed33c73594f359d7e6" + +[[package]] +name = "log" +version = "0.4.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fabed175da42fed1fa0746b0ea71f412aa9d35e76e95e59b192c64b9dc2bf8b" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "maplit" +version = "1.0.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3e2e65a1a2e43cfcb47a895c4c8b10d1f4a61097f9f254f183aee60cad9c651d" + +[[package]] +name = "matches" +version = "0.1.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ffc5c5338469d4d3ea17d269fa8ea3512ad247247c30bd2df69e68309ed0a08" + +[[package]] +name = "mdman" +version = "0.1.0" +dependencies = [ + "anyhow", + "handlebars", + "pretty_assertions", + "pulldown-cmark", + "same-file", + "serde_json", + "url", +] + +[[package]] +name = "memchr" +version = "2.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3728d817d99e5ac407411fa471ff9800a778d88a24685968b36824eaf4bee400" + +[[package]] +name = "opaque-debug" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2839e79665f131bdb5782e51f2c6c9599c133c6098982a54c794358bf432529c" + +[[package]] +name = "output_vt100" +version = "0.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53cdc5b785b7a58c5aad8216b3dfa114df64b0b06ae6e1501cef91df2fbdf8f9" +dependencies = [ + "winapi", +] + +[[package]] +name = "percent-encoding" +version = "2.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d4fd5641d01c8f18a23da7b6fe29298ff4b55afcccdf78973b24cf3175fee32e" + +[[package]] +name = "pest" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10f4872ae94d7b90ae48754df22fd42ad52ce740b8f370b03da4835417403e53" +dependencies = [ + "ucd-trie", +] + +[[package]] +name = "pest_derive" +version = "2.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "833d1ae558dc601e9a60366421196a8d94bc0ac980476d0b67e1d0988d72b2d0" +dependencies = [ + "pest", + "pest_generator", +] + +[[package]] +name = "pest_generator" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "99b8db626e31e5b81787b9783425769681b347011cc59471e33ea46d2ea0cf55" +dependencies = [ + "pest", + "pest_meta", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "pest_meta" +version = "2.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "54be6e404f5317079812fc8f9f5279de376d8856929e21c184ecf6bbd692a11d" +dependencies = [ + "maplit", + "pest", + "sha-1", +] + +[[package]] +name = "pretty_assertions" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f81e1644e1b54f5a68959a29aa86cde704219254669da328ecfdf6a1f09d427" +dependencies = [ + "ansi_term", + "ctor", + "difference", + "output_vt100", +] + +[[package]] +name = "proc-macro2" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "04f5f085b5d71e2188cb8271e5da0161ad52c3f227a661a3c135fdf28e258b12" +dependencies = [ + "unicode-xid", +] + +[[package]] +name = "pulldown-cmark" +version = "0.7.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca36dea94d187597e104a5c8e4b07576a8a45aa5db48a65e12940d3eb7461f55" +dependencies = [ + "bitflags", + "memchr", + "unicase", +] + +[[package]] +name = "quick-error" +version = "1.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0" + +[[package]] +name = "quote" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aa563d17ecb180e500da1cfd2b028310ac758de548efdd203e18f283af693f37" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "ryu" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "71d301d4193d031abdd79ff7e3dd721168a9572ef3fe51a1517aba235bd8f86e" + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "serde" +version = "1.0.114" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5317f7588f0a5078ee60ef675ef96735a1442132dc645eb1d12c018620ed8cd3" + +[[package]] +name = "serde_json" +version = "1.0.57" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "164eacbdb13512ec2745fb09d51fd5b22b0d65ed294a1dcf7285a360c80a675c" +dependencies = [ + "itoa", + "ryu", + "serde", +] + +[[package]] +name = "sha-1" +version = "0.8.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f7d94d0bede923b3cea61f3f1ff57ff8cdfd77b400fb8f9998949e0cf04163df" +dependencies = [ + "block-buffer", + "digest", + "fake-simd", + "opaque-debug", +] + +[[package]] +name = "syn" +version = "1.0.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4cdb98bcb1f9d81d07b536179c269ea15999b5d14ea958196413869445bb5250" +dependencies = [ + "proc-macro2", + "quote", + "unicode-xid", +] + +[[package]] +name = "tinyvec" +version = "0.3.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53953d2d3a5ad81d9f844a32f14ebb121f50b650cd59d0ee2a07cf13c617efed" + +[[package]] +name = "typenum" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "373c8a200f9e67a0c95e62a4f52fbf80c23b4381c05a17845531982fa99e6b33" + +[[package]] +name = "ucd-trie" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56dee185309b50d1f11bfedef0fe6d036842e3fb77413abef29f8f8d1c5d4c1c" + +[[package]] +name = "unicase" +version = "2.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "50f37be617794602aabbeee0be4f259dc1778fabe05e2d67ee8f79326d5cb4f6" +dependencies = [ + "version_check", +] + +[[package]] +name = "unicode-bidi" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "49f2bd0c6468a8230e1db229cff8029217cf623c767ea5d60bfbd42729ea54d5" +dependencies = [ + "matches", +] + +[[package]] +name = "unicode-normalization" +version = "0.1.13" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6fb19cf769fa8c6a80a162df694621ebeb4dafb606470b2b2fce0be40a98a977" +dependencies = [ + "tinyvec", +] + +[[package]] +name = "unicode-xid" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f7fe0bb3479651439c9112f72b6c505038574c9fbb575ed1bf3b797fa39dd564" + +[[package]] +name = "url" +version = "2.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "829d4a8476c35c9bf0bbce5a3b23f4106f79728039b726d292bb93bc106787cb" +dependencies = [ + "idna", + "matches", + "percent-encoding", +] + +[[package]] +name = "version_check" +version = "0.9.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b5a972e5669d67ba988ce3dc826706fb0a8b01471c088cb0b6110b805cc36aed" + +[[package]] +name = "walkdir" +version = "2.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "777182bc735b6424e1a57516d35ed72cb8019d85c8c9bf536dccb3445c1a2f7d" +dependencies = [ + "same-file", + "winapi", + "winapi-util", +] + +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + +[[package]] +name = "winapi-util" +version = "0.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "70ec6ce85bb158151cae5e5c87f95a8e97d2c0c4b001223f33a334e3ce5de178" +dependencies = [ + "winapi", +] + +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" diff --git a/crates/mdman/Cargo.toml b/crates/mdman/Cargo.toml new file mode 100644 index 00000000000..9d4329a16f8 --- /dev/null +++ b/crates/mdman/Cargo.toml @@ -0,0 +1,18 @@ +[package] +name = "mdman" +version = "0.1.0" +authors = ["Eric Huss"] +edition = "2018" +license = "MIT OR Apache-2.0" +description = "Creates a man page page from markdown." + +[dependencies] +anyhow = "1.0.31" +handlebars = { version = "3.2.1", features = ["dir_source"] } +pulldown-cmark = { version = "0.7.2", default-features = false } +same-file = "1.0.6" +serde_json = "1.0.56" +url = "2.1.1" + +[dev-dependencies] +pretty_assertions = "0.6.1" diff --git a/crates/mdman/README.md b/crates/mdman/README.md new file mode 100644 index 00000000000..e28b596ba34 --- /dev/null +++ b/crates/mdman/README.md @@ -0,0 +1,7 @@ +# mdman + +mdman is a small utility for creating man pages from markdown text files. + +## Usage + +See the [man page](doc/out/mdman.md) generated by this tool. diff --git a/crates/mdman/build-man.sh b/crates/mdman/build-man.sh new file mode 100755 index 00000000000..9286b17c2f1 --- /dev/null +++ b/crates/mdman/build-man.sh @@ -0,0 +1,7 @@ +#!/bin/bash + +set -e + +cargo run -- -t md -o doc/out doc/*.md +cargo run -- -t txt -o doc/out doc/*.md +cargo run -- -t man -o doc/out doc/*.md diff --git a/crates/mdman/doc/mdman.md b/crates/mdman/doc/mdman.md new file mode 100644 index 00000000000..30d07139be2 --- /dev/null +++ b/crates/mdman/doc/mdman.md @@ -0,0 +1,95 @@ +# mdman(1) + +## NAME + +mdman - Converts markdown to a man page + +## SYNOPSIS + +`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._ + +## DESCRIPTION + +Converts a markdown file to a man page. + +The source file is first processed as a +[handlebars](https://handlebarsjs.com/) template. Then, it is processed as +markdown into the target format. This supports different output formats, +such as troff or plain text. + +Every man page should start with a level-1 header with the man name and +section, such as `# mdman(1)`. + +The handlebars template has several special tags to assist with generating the +man page: + +{{{{raw}}}} +- Every block of command-line options must be wrapped between `{{#options}}` + and `{{/options}}` tags. This tells the processor where the options start + and end. +- Each option must be expressed with a `{{#option}}` block. The parameters to + the the block are a sequence of strings indicating the option. For example, + ```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that + has two different forms. The text within the string is processed as markdown. + It is recommended to use formatting similar to this example. + + The content of the `{{#option}}` block should contain a detailed description + of the option. + + Use the `{{/option}}` tag to end the option block. +- References to other man pages should use the `{{man name section}}` + expression. For example, `{{man "mdman" 1}}` will generate a reference to + the `mdman(1)` man page. For non-troff output, the `--man` option will tell + `mdman` how to create links to the man page. If there is no matching `--man` + option, then it links to a file named _name_`.md` in the same directory. +- Variables can be set with `{{*set name="value"}}`. These variables can + then be referenced with `{{name}}` expressions. +- Partial templates should be placed in a directory named `includes` + next to the source file. Templates can be included with an expression like + `{{> template-name}}`. +- Other helpers include: + - `{{lower value}}` Converts the given value to lowercase. +{{{{/raw}}}} + +## OPTIONS + +{{#options}} + +{{#option "`-t` _type_"}} +Specifies the output type. The following output types are supported: +- `man` — A troff-style man page. Outputs with a numbered extension (like + `.1`) matching the man page section. +- `md` — A markdown file, after all handlebars processing has been finished. + Outputs with the `.md` extension. +- `txt` — A text file, rendered for situations where a man page viewer isn't + available. Outputs with the `.txt` extension. +{{/option}} + +{{#option "`-o` _outdir_"}} +Specifies the directory where to save the output. +{{/option}} + +{{#option "`--url` _base_url_"}} +Specifies a base URL to use for relative URLs within the document. Any +relative URL will be joined with this URL. +{{/option}} + +{{#option "`--man` _name_`:`_section_`=`_url_"}} +Specifies a URL to use for the given man page. When the `\{{man name +section}}` expression is used, the given URL will be inserted as a link. This +may be specified multiple times. If a man page reference does not have a +matching `--man` entry, then a relative link to a file named _name_`.md` will +be used. +{{/option}} + +{{#option "_sources..._"}} +The source input filename, may be specified multiple times. +{{/option}} + +{{/options}} + +## EXAMPLES + +1. Convert the given documents to man pages: + + mdman -t man -o doc doc/mdman.md diff --git a/crates/mdman/doc/out/mdman.1 b/crates/mdman/doc/out/mdman.1 new file mode 100644 index 00000000000..c3a626d2510 --- /dev/null +++ b/crates/mdman/doc/out/mdman.1 @@ -0,0 +1,124 @@ +'\" t +.TH "MDMAN" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +mdman \- Converts markdown to a man page +.SH "SYNOPSIS" +\fBmdman\fR [\fIoptions\fR] \fB\-t\fR \fItype\fR \fB\-o\fR \fIoutdir\fR \fIsources...\fR +.SH "DESCRIPTION" +Converts a markdown file to a man page. +.sp +The source file is first processed as a +\fIhandlebars\fR template. Then, it is processed as +markdown into the target format. This supports different output formats, +such as troff or plain text. +.sp +Every man page should start with a level\-1 header with the man name and +section, such as \fB# mdman(1)\fR\&. +.sp +The handlebars template has several special tags to assist with generating the +man page: +.sp +.RS 4 +\h'-04'\(bu\h'+02'Every block of command\-line options must be wrapped between \fB{{#options}}\fR +and \fB{{/options}}\fR tags. This tells the processor where the options start +and end. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Each option must be expressed with a \fB{{#option}}\fR block. The parameters to +the the block are a sequence of strings indicating the option. For example, +\fB{{#option "`\-p` _spec_..." "`\-\-package` _spec_..."}}\fR is an option that +has two different forms. The text within the string is processed as markdown. +It is recommended to use formatting similar to this example. +.sp +The content of the \fB{{#option}}\fR block should contain a detailed description +of the option. +.sp +Use the \fB{{/option}}\fR tag to end the option block. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'References to other man pages should use the \fB{{man name section}}\fR +expression. For example, \fB{{man "mdman" 1}}\fR will generate a reference to +the \fBmdman(1)\fR man page. For non\-troff output, the \fB\-\-man\fR option will tell +\fBmdman\fR how to create links to the man page. If there is no matching \fB\-\-man\fR +option, then it links to a file named \fIname\fR\fB\&.md\fR in the same directory. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Variables can be set with \fB{{*set name="value"}}\fR\&. These variables can +then be referenced with \fB{{name}}\fR expressions. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Partial templates should be placed in a directory named \fBincludes\fR +next to the source file. Templates can be included with an expression like +\fB{{> template\-name}}\fR\&. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Other helpers include: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fB{{lower value}}\fR Converts the given value to lowercase. +.RE +.RE +.SH "OPTIONS" +.sp +\fB\-t\fR \fItype\fR +.RS 4 +Specifies the output type. The following output types are supported: +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBman\fR \[em]\ A troff\-style man page. Outputs with a numbered extension (like +\fB\&.1\fR) matching the man page section. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBmd\fR \[em]\ A markdown file, after all handlebars processing has been finished. +Outputs with the \fB\&.md\fR extension. +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'\fBtxt\fR \[em]\ A text file, rendered for situations where a man page viewer isn't +available. Outputs with the \fB\&.txt\fR extension. +.RE +.RE +.sp +\fB\-o\fR \fIoutdir\fR +.RS 4 +Specifies the directory where to save the output. +.RE +.sp +\fB\-\-url\fR \fIbase_url\fR +.RS 4 +Specifies a base URL to use for relative URLs within the document. Any +relative URL will be joined with this URL. +.RE +.sp +\fB\-\-man\fR \fIname\fR\fB:\fR\fIsection\fR\fB=\fR\fIurl\fR +.RS 4 +Specifies a URL to use for the given man page. When the \fB{{man name section}}\fR expression is used, the given URL will be inserted as a link. This +may be specified multiple times. If a man page reference does not have a +matching \fB\-\-man\fR entry, then a relative link to a file named \fIname\fR\fB\&.md\fR will +be used. +.RE +.sp +\fIsources...\fR +.RS 4 +The source input filename, may be specified multiple times. +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'Convert the given documents to man pages: +.sp +.RS 4 +.nf +mdman \-t man \-o doc doc/mdman.md +.fi +.RE +.RE diff --git a/crates/mdman/doc/out/mdman.md b/crates/mdman/doc/out/mdman.md new file mode 100644 index 00000000000..47b2b625d28 --- /dev/null +++ b/crates/mdman/doc/out/mdman.md @@ -0,0 +1,95 @@ +# mdman(1) + +## NAME + +mdman - Converts markdown to a man page + +## SYNOPSIS + +`mdman` [_options_] `-t` _type_ `-o` _outdir_ _sources..._ + +## DESCRIPTION + +Converts a markdown file to a man page. + +The source file is first processed as a +[handlebars](https://handlebarsjs.com/) template. Then, it is processed as +markdown into the target format. This supports different output formats, +such as troff or plain text. + +Every man page should start with a level-1 header with the man name and +section, such as `# mdman(1)`. + +The handlebars template has several special tags to assist with generating the +man page: + +- Every block of command-line options must be wrapped between `{{#options}}` + and `{{/options}}` tags. This tells the processor where the options start + and end. +- Each option must be expressed with a `{{#option}}` block. The parameters to + the the block are a sequence of strings indicating the option. For example, + ```{{#option "`-p` _spec_..." "`--package` _spec_..."}}``` is an option that + has two different forms. The text within the string is processed as markdown. + It is recommended to use formatting similar to this example. + + The content of the `{{#option}}` block should contain a detailed description + of the option. + + Use the `{{/option}}` tag to end the option block. +- References to other man pages should use the `{{man name section}}` + expression. For example, `{{man "mdman" 1}}` will generate a reference to + the `mdman(1)` man page. For non-troff output, the `--man` option will tell + `mdman` how to create links to the man page. If there is no matching `--man` + option, then it links to a file named _name_`.md` in the same directory. +- Variables can be set with `{{*set name="value"}}`. These variables can + then be referenced with `{{name}}` expressions. +- Partial templates should be placed in a directory named `includes` + next to the source file. Templates can be included with an expression like + `{{> template-name}}`. +- Other helpers include: + - `{{lower value}}` Converts the given value to lowercase. + + +## OPTIONS + +
+ +
-t type
+
Specifies the output type. The following output types are supported:

+
    +
  • man — A troff-style man page. Outputs with a numbered extension (like +.1) matching the man page section.
    • +
  • md — A markdown file, after all handlebars processing has been finished. +Outputs with the .md extension.
    • +
  • txt — A text file, rendered for situations where a man page viewer isn't +available. Outputs with the .txt extension.
    • +
+ + +
-o outdir
+
Specifies the directory where to save the output.
+ + +
--url base_url
+
Specifies a base URL to use for relative URLs within the document. Any +relative URL will be joined with this URL.
+ + +
--man name:section=url
+
Specifies a URL to use for the given man page. When the {{man name section}} expression is used, the given URL will be inserted as a link. This +may be specified multiple times. If a man page reference does not have a +matching --man entry, then a relative link to a file named name.md will +be used.
+ + +
sources...
+
The source input filename, may be specified multiple times.
+ + +
+ +## EXAMPLES + +1. Convert the given documents to man pages: + + mdman -t man -o doc doc/mdman.md diff --git a/crates/mdman/doc/out/mdman.txt b/crates/mdman/doc/out/mdman.txt new file mode 100644 index 00000000000..b6911bf4c64 --- /dev/null +++ b/crates/mdman/doc/out/mdman.txt @@ -0,0 +1,91 @@ +MDMAN(1) + +NAME + mdman - Converts markdown to a man page + +SYNOPSIS + mdman [options] -t type -o outdir sources... + +DESCRIPTION + Converts a markdown file to a man page. + + The source file is first processed as a handlebars + template. Then, it is processed as markdown + into the target format. This supports different output formats, such as + troff or plain text. + + Every man page should start with a level-1 header with the man name and + section, such as # mdman(1). + + The handlebars template has several special tags to assist with + generating the man page: + + o Every block of command-line options must be wrapped between + {{#options}} and {{/options}} tags. This tells the processor where + the options start and end. + + o Each option must be expressed with a {{#option}} block. The + parameters to the the block are a sequence of strings indicating the + option. For example, {{#option "`-p` _spec_..." "`--package` + _spec_..."}} is an option that has two different forms. The text + within the string is processed as markdown. It is recommended to use + formatting similar to this example. + + The content of the {{#option}} block should contain a detailed + description of the option. + + Use the {{/option}} tag to end the option block. + + o References to other man pages should use the {{man name section}} + expression. For example, {{man "mdman" 1}} will generate a reference + to the mdman(1) man page. For non-troff output, the --man option will + tell mdman how to create links to the man page. If there is no + matching --man option, then it links to a file named name.md in the + same directory. + + o Variables can be set with {{*set name="value"}}. These variables can + then be referenced with {{name}} expressions. + + o Partial templates should be placed in a directory named includes next + to the source file. Templates can be included with an expression like + {{> template-name}}. + + o Other helpers include: + + o {{lower value}} Converts the given value to lowercase. + +OPTIONS + -t type + Specifies the output type. The following output types are supported: + + o man — A troff-style man page. Outputs with a numbered + extension (like .1) matching the man page section. + + o md — A markdown file, after all handlebars processing has been + finished. Outputs with the .md extension. + + o txt — A text file, rendered for situations where a man page + viewer isn't available. Outputs with the .txt extension. + + -o outdir + Specifies the directory where to save the output. + + --url base_url + Specifies a base URL to use for relative URLs within the document. + Any relative URL will be joined with this URL. + + --man name:section=url + Specifies a URL to use for the given man page. When the {{man name + section}} expression is used, the given URL will be inserted as a + link. This may be specified multiple times. If a man page reference + does not have a matching --man entry, then a relative link to a file + named name.md will be used. + + sources... + The source input filename, may be specified multiple times. + +EXAMPLES + 1. Convert the given documents to man pages: + + mdman -t man -o doc doc/mdman.md + diff --git a/crates/mdman/src/format.rs b/crates/mdman/src/format.rs new file mode 100644 index 00000000000..7bc9781b907 --- /dev/null +++ b/crates/mdman/src/format.rs @@ -0,0 +1,20 @@ +use anyhow::Error; + +pub mod man; +pub mod md; +pub mod text; + +pub trait Formatter { + /// Renders the given markdown to the formatter's output. + fn render(&self, input: &str) -> Result; + /// Renders the start of a block of options (triggered by `{{#options}}`). + fn render_options_start(&self) -> &'static str; + /// Renders the end of a block of options (triggered by `{{/options}}`). + fn render_options_end(&self) -> &'static str; + /// Renders an option (triggered by `{{#option}}`). + fn render_option(&self, params: &[&str], block: &str, man_name: &str) -> Result; + /// Converts a man page reference into markdown that is appropriate for this format. + /// + /// Triggered by `{{man name section}}`. + fn linkify_man_to_md(&self, name: &str, section: u8) -> Result; +} diff --git a/crates/mdman/src/format/man.rs b/crates/mdman/src/format/man.rs new file mode 100644 index 00000000000..1962be2fe55 --- /dev/null +++ b/crates/mdman/src/format/man.rs @@ -0,0 +1,430 @@ +//! Man-page formatter. + +use crate::util::{header_text, parse_name_and_section}; +use crate::EventIter; +use anyhow::{bail, Error}; +use pulldown_cmark::{Alignment, Event, LinkType, Tag}; +use std::fmt::Write; +use url::Url; + +pub struct ManFormatter { + url: Option, +} + +impl ManFormatter { + pub fn new(url: Option) -> ManFormatter { + ManFormatter { url } + } +} + +impl super::Formatter for ManFormatter { + fn render(&self, input: &str) -> Result { + ManRenderer::render(input, self.url.clone()) + } + + fn render_options_start(&self) -> &'static str { + // Tell pulldown_cmark to ignore this. + // This will be stripped out later. + " &'static str { + "]]>" + } + + fn render_option( + &self, + params: &[&str], + block: &str, + _man_name: &str, + ) -> Result { + let rendered_options = params + .iter() + .map(|param| { + let r = self.render(param)?; + Ok(r.trim().trim_start_matches(".sp").to_string()) + }) + .collect::, Error>>()?; + let rendered_block = self.render(block)?; + let rendered_block = rendered_block.trim().trim_start_matches(".sp").trim(); + // .RS = move left margin to right 4. + // .RE = move margin back one level. + Ok(format!( + "\n.sp\n{}\n.RS 4\n{}\n.RE\n", + rendered_options.join(", "), + rendered_block + )) + } + + fn linkify_man_to_md(&self, name: &str, section: u8) -> Result { + Ok(format!("`{}`({})", name, section)) + } +} + +#[derive(Copy, Clone)] +enum Font { + Bold, + Italic, +} + +impl Font { + fn str_from_stack(font_stack: &[Font]) -> &'static str { + let has_bold = font_stack.iter().any(|font| matches!(font, Font::Bold)); + let has_italic = font_stack.iter().any(|font| matches!(font, Font::Italic)); + match (has_bold, has_italic) { + (false, false) => "\\fR", // roman (normal) + (false, true) => "\\fI", // italic + (true, false) => "\\fB", // bold + (true, true) => "\\f(BI", // bold italic + } + } +} + +struct ManRenderer<'e> { + output: String, + parser: EventIter<'e>, + font_stack: Vec, +} + +impl<'e> ManRenderer<'e> { + fn render(input: &str, url: Option) -> Result { + let parser = crate::md_parser(input, url); + let output = String::with_capacity(input.len() * 3 / 2); + let mut mr = ManRenderer { + parser, + output, + font_stack: Vec::new(), + }; + mr.push_man()?; + Ok(mr.output) + } + + fn push_man(&mut self) -> Result<(), Error> { + // If this is true, this is inside a cdata block used for hiding + // content from pulldown_cmark. + let mut in_cdata = false; + // The current list stack. None if unordered, Some if ordered with the + // given number as the current index. + let mut list: Vec> = Vec::new(); + // Used in some cases where spacing isn't desired. + let mut suppress_paragraph = false; + let mut table_cell_index = 0; + + while let Some((event, range)) = self.parser.next() { + let this_suppress_paragraph = suppress_paragraph; + suppress_paragraph = false; + match event { + Event::Start(tag) => { + match tag { + Tag::Paragraph => { + if !this_suppress_paragraph { + self.flush(); + self.output.push_str(".sp\n"); + } + } + Tag::Heading(n) => { + if n == 1 { + self.push_top_header()?; + } else if n == 2 { + // Section header + let text = header_text(&mut self.parser)?; + self.flush(); + write!(self.output, ".SH \"{}\"\n", text)?; + suppress_paragraph = true; + } else { + // Subsection header + let text = header_text(&mut self.parser)?; + self.flush(); + write!(self.output, ".SS \"{}\"\n", text)?; + suppress_paragraph = true; + } + } + Tag::BlockQuote => { + self.flush(); + // .RS = move left margin over 3 + // .ll = shrink line length + self.output.push_str(".RS 3\n.ll -5\n.sp\n"); + suppress_paragraph = true; + } + Tag::CodeBlock(_kind) => { + // space down, indent 4, no-fill mode + self.flush(); + self.output.push_str(".sp\n.RS 4\n.nf\n"); + } + Tag::List(start) => list.push(start), + Tag::Item => { + // Note: This uses explicit movement instead of .IP + // because the spacing on .IP looks weird to me. + // space down, indent 4 + self.flush(); + self.output.push_str(".sp\n.RS 4\n"); + match list.last_mut().expect("item must have list start") { + // Ordered list. + Some(n) => { + // move left 4, output the list index number, move right 1. + write!(self.output, "\\h'-04' {}.\\h'+01'", n)?; + *n += 1; + } + // Unordered list. + None => self.output.push_str("\\h'-04'\\(bu\\h'+02'"), + } + suppress_paragraph = true; + } + Tag::FootnoteDefinition(_label) => unimplemented!(), + Tag::Table(alignment) => { + // Table start + // allbox = draw a box around all the cells + // tab(:) = Use `:` to separate cell data (instead of tab) + // ; = end of options + self.output.push_str( + "\n.TS\n\ + allbox tab(:);\n", + ); + let alignments: Vec<_> = alignment + .iter() + .map(|a| match a { + Alignment::Left | Alignment::None => "lt", + Alignment::Center => "ct", + Alignment::Right => "rt", + }) + .collect(); + self.output.push_str(&alignments.join(" ")); + self.output.push_str(".\n"); + table_cell_index = 0; + } + Tag::TableHead => { + table_cell_index = 0; + } + Tag::TableRow => { + table_cell_index = 0; + self.output.push('\n'); + } + Tag::TableCell => { + if table_cell_index != 0 { + // Separator between columns. + self.output.push(':'); + } + // Start a text block. + self.output.push_str("T{\n"); + table_cell_index += 1 + } + Tag::Emphasis => self.push_font(Font::Italic), + Tag::Strong => self.push_font(Font::Bold), + // Strikethrough isn't usually supported for TTY. + Tag::Strikethrough => self.output.push_str("~~"), + Tag::Link(link_type, dest_url, _title) => { + if dest_url.starts_with('#') { + // In a man page, page-relative anchors don't + // have much meaning. + continue; + } + match link_type { + LinkType::Autolink | LinkType::Email => { + // The text is a copy of the URL, which is not needed. + match self.parser.next() { + Some((Event::Text(_), _range)) => {} + _ => bail!("expected text after autolink"), + } + } + LinkType::Inline + | LinkType::Reference + | LinkType::Collapsed + | LinkType::Shortcut => { + self.push_font(Font::Italic); + } + // This is currently unused. This is only + // emitted with a broken link callback, but I + // felt it is too annoying to escape `[` in + // option descriptions. + LinkType::ReferenceUnknown + | LinkType::CollapsedUnknown + | LinkType::ShortcutUnknown => { + bail!( + "link with missing reference `{}` located at offset {}", + dest_url, + range.start + ); + } + } + } + Tag::Image(_link_type, _dest_url, _title) => { + bail!("images are not currently supported") + } + } + } + Event::End(tag) => { + match &tag { + Tag::Paragraph => self.flush(), + Tag::Heading(_n) => {} + Tag::BlockQuote => { + self.flush(); + // restore left margin, restore line length + self.output.push_str(".br\n.RE\n.ll\n"); + } + Tag::CodeBlock(_kind) => { + self.flush(); + // Restore fill mode, move margin back one level. + self.output.push_str(".fi\n.RE\n"); + } + Tag::List(_) => { + list.pop(); + } + Tag::Item => { + self.flush(); + // Move margin back one level. + self.output.push_str(".RE\n"); + } + Tag::FootnoteDefinition(_label) => {} + Tag::Table(_) => { + // Table end + // I don't know why, but the .sp is needed to provide + // space with the following content. + self.output.push_str("\n.TE\n.sp\n"); + } + Tag::TableHead => {} + Tag::TableRow => {} + Tag::TableCell => { + // End text block. + self.output.push_str("\nT}"); + } + Tag::Emphasis | Tag::Strong => self.pop_font(), + Tag::Strikethrough => self.output.push_str("~~"), + Tag::Link(link_type, dest_url, _title) => { + if dest_url.starts_with('#') { + continue; + } + match link_type { + LinkType::Autolink | LinkType::Email => {} + LinkType::Inline + | LinkType::Reference + | LinkType::Collapsed + | LinkType::Shortcut => { + self.pop_font(); + self.output.push(' '); + } + _ => { + panic!("unexpected tag {:?}", tag); + } + } + write!(self.output, "<{}>", escape(&dest_url)?)?; + } + Tag::Image(_link_type, _dest_url, _title) => {} + } + } + Event::Text(t) => { + self.output.push_str(&escape(&t)?); + } + Event::Code(t) => { + self.push_font(Font::Bold); + self.output.push_str(&escape(&t)?); + self.pop_font(); + } + Event::Html(t) => { + if t.starts_with("") { + in_cdata = false; + } else if !t.trim().is_empty() { + self.output.push_str(&t); + } + } else { + self.output.push_str(&escape(&t)?); + } + } + Event::FootnoteReference(_t) => {} + Event::SoftBreak => self.output.push('\n'), + Event::HardBreak => { + self.flush(); + self.output.push_str(".br\n"); + } + Event::Rule => { + self.flush(); + // \l' **length** ' Draw horizontal line (default underscore). + // \n(.lu Gets value from register "lu" (current line length) + self.output.push_str("\\l'\\n(.lu'\n"); + } + Event::TaskListMarker(_b) => unimplemented!(), + } + } + Ok(()) + } + + fn flush(&mut self) { + if !self.output.ends_with('\n') { + self.output.push('\n'); + } + } + + /// Switch to the given font. + /// + /// Because the troff sequence `\fP` for switching to the "previous" font + /// doesn't support nesting, this needs to emulate it here. This is needed + /// for situations like **hi _there_**. + fn push_font(&mut self, font: Font) { + self.font_stack.push(font); + self.output.push_str(Font::str_from_stack(&self.font_stack)); + } + + fn pop_font(&mut self) { + self.font_stack.pop(); + self.output.push_str(Font::str_from_stack(&self.font_stack)); + } + + /// Parse and render the first top-level header of the document. + fn push_top_header(&mut self) -> Result<(), Error> { + // This enables the tbl preprocessor for tables. + // This seems to be enabled by default on every modern system I could + // find, but it doesn't seem to hurt to enable this. + self.output.push_str("'\\\" t\n"); + // Extract the name of the man page. + let text = header_text(&mut self.parser)?; + let (name, section) = parse_name_and_section(&text)?; + // .TH = Table header + // .nh = disable hyphenation + // .ad l = Left-adjust mode (disable justified). + // .ss sets sentence_space_size to 0 (prevents double spaces after . + // if . is last on the line) + write!( + self.output, + ".TH \"{}\" \"{}\"\n\ + .nh\n\ + .ad l\n\ + .ss \\n[.ss] 0\n", + escape(&name.to_uppercase())?, + section + )?; + Ok(()) + } +} + +fn escape(s: &str) -> Result { + let mut replaced = s + .replace('\\', "\\(rs") + .replace('-', "\\-") + .replace('\u{00A0}', "\\ ") // non-breaking space (non-stretchable) + .replace('–', "\\[en]") // \u{2013} en-dash + .replace('—', "\\[em]") // \u{2014} em-dash + .replace('│', "|") // \u{2502} box drawing light vertical (could use \[br]) + .replace('├', "|") // \u{251C} box drawings light vertical and right + .replace('└', "`") // \u{2514} box drawings light up and right + .replace('─', "\\-") // \u{2500} box drawing light horizontal + ; + if replaced.starts_with('.') { + replaced = format!("\\&.{}", &replaced[1..]); + } else if replaced.starts_with('\'') { + replaced = format!("\\(aq{}", &replaced[1..]); + } + + if let Some(ch) = replaced.chars().find(|ch| { + !matches!(ch, '\n' | ' ' | '!'..='/' | '0'..='9' + | ':'..='@' | 'A'..='Z' | '['..='`' | 'a'..='z' | '{'..='~') + }) { + bail!( + "character {:?} is not allowed (update the translation table if needed)", + ch + ); + } + Ok(replaced) +} diff --git a/crates/mdman/src/format/md.rs b/crates/mdman/src/format/md.rs new file mode 100644 index 00000000000..037807eb541 --- /dev/null +++ b/crates/mdman/src/format/md.rs @@ -0,0 +1,114 @@ +//! Markdown formatter. + +use crate::util::unwrap; +use crate::ManMap; +use anyhow::{bail, format_err, Error}; +use std::fmt::Write; +use url::Url; + +pub struct MdFormatter { + url: Option, + man_map: ManMap, +} + +impl MdFormatter { + pub fn new(url: Option, man_map: ManMap) -> MdFormatter { + MdFormatter { url, man_map } + } +} + +impl MdFormatter { + fn render_html(&self, input: &str) -> Result { + let parser = crate::md_parser(input, self.url.clone()); + let mut html_output: String = String::with_capacity(input.len() * 3 / 2); + pulldown_cmark::html::push_html(&mut html_output, parser.map(|(e, _r)| e)); + Ok(html_output) + } +} + +impl super::Formatter for MdFormatter { + fn render(&self, input: &str) -> Result { + Ok(input.to_string()) + } + + fn render_options_start(&self) -> &'static str { + "
" + } + + fn render_options_end(&self) -> &'static str { + "
" + } + + fn render_option(&self, params: &[&str], block: &str, man_name: &str) -> Result { + let mut result = String::new(); + fn unwrap_p(t: &str) -> &str { + unwrap(t, "

", "

") + } + + for param in params { + let rendered = self.render_html(param)?; + let no_p = unwrap_p(&rendered); + // split out first term to use as the id. + let first = no_p + .split_whitespace() + .next() + .ok_or_else(|| format_err!("did not expect option `{}` to be empty", param))?; + let no_tags = trim_tags(first); + if no_tags.is_empty() { + bail!("unexpected empty option with no tags `{}`", param); + } + let id = format!("option-{}-{}", man_name, no_tags); + write!( + result, + "
\ + {OPTION}
\n", + ID = id, + OPTION = no_p + )?; + } + let rendered_block = self.render_html(block)?; + write!( + result, + "
{}
\n", + unwrap_p(&rendered_block) + )?; + Ok(result) + } + + fn linkify_man_to_md(&self, name: &str, section: u8) -> Result { + let s = match self.man_map.get(&(name.to_string(), section)) { + Some(link) => format!("[{}({})]({})", name, section, link), + None => format!("[{}({})]({}.md)", name, section, name), + }; + Ok(s) + } +} + +fn trim_tags(s: &str) -> String { + // This is a hack. It removes all HTML tags. + let mut in_tag = false; + let mut in_char_ref = false; + s.chars() + .filter(|&ch| match ch { + '<' if in_tag => panic!("unexpected nested tag"), + '&' if in_char_ref => panic!("unexpected nested char ref"), + '<' => { + in_tag = true; + false + } + '&' => { + in_char_ref = true; + false + } + '>' if in_tag => { + in_tag = false; + false + } + ';' if in_char_ref => { + in_char_ref = false; + false + } + _ => !in_tag && !in_char_ref, + }) + .collect() +} diff --git a/crates/mdman/src/format/text.rs b/crates/mdman/src/format/text.rs new file mode 100644 index 00000000000..2c6a4ff1747 --- /dev/null +++ b/crates/mdman/src/format/text.rs @@ -0,0 +1,605 @@ +//! Text formatter. + +use crate::util::{header_text, unwrap}; +use crate::EventIter; +use anyhow::{bail, Error}; +use pulldown_cmark::{Alignment, Event, LinkType, Tag}; +use std::fmt::Write; +use std::mem; +use url::Url; + +pub struct TextFormatter { + url: Option, +} + +impl TextFormatter { + pub fn new(url: Option) -> TextFormatter { + TextFormatter { url } + } +} + +impl super::Formatter for TextFormatter { + fn render(&self, input: &str) -> Result { + TextRenderer::render(input, self.url.clone(), 0) + } + + fn render_options_start(&self) -> &'static str { + // Tell pulldown_cmark to ignore this. + // This will be stripped out later. + " &'static str { + "]]>" + } + + fn render_option( + &self, + params: &[&str], + block: &str, + _man_name: &str, + ) -> Result { + let rendered_options = params + .iter() + .map(|param| TextRenderer::render(param, self.url.clone(), 0)) + .collect::, Error>>()?; + let trimmed: Vec<_> = rendered_options.iter().map(|o| o.trim()).collect(); + // Wrap in HTML tags, they will be stripped out during rendering. + Ok(format!( + "
{}
\n
{}
\n
\n", + trimmed.join(", "), + block + )) + } + + fn linkify_man_to_md(&self, name: &str, section: u8) -> Result { + Ok(format!("`{}`({})", name, section)) + } +} + +struct TextRenderer<'e> { + output: String, + indent: usize, + /// The current line being written. Once a line break is encountered (such + /// as starting a new paragraph), this will be written to `output` via + /// `flush`. + line: String, + /// The current word being written. Once a break is encountered (such as a + /// space) this will be written to `line` via `flush_word`. + word: String, + parser: EventIter<'e>, + /// The base URL used for relative URLs. + url: Option, + table: Table, +} + +impl<'e> TextRenderer<'e> { + fn render(input: &str, url: Option, indent: usize) -> Result { + let parser = crate::md_parser(input, url.clone()); + let output = String::with_capacity(input.len() * 3 / 2); + let mut mr = TextRenderer { + output, + indent, + line: String::new(), + word: String::new(), + parser, + url, + table: Table::new(), + }; + mr.push_md()?; + Ok(mr.output) + } + + fn push_md(&mut self) -> Result<(), Error> { + // If this is true, this is inside a cdata block used for hiding + // content from pulldown_cmark. + let mut in_cdata = false; + // The current list stack. None if unordered, Some if ordered with the + // given number as the current index. + let mut list: Vec> = Vec::new(); + // Used in some cases where spacing isn't desired. + let mut suppress_paragraph = false; + // Whether or not word-wrapping is enabled. + let mut wrap_text = true; + + while let Some((event, range)) = self.parser.next() { + let this_suppress_paragraph = suppress_paragraph; + // Always reset suppression, even if the next event isn't a + // paragraph. This is in essence, a 1-token lookahead where the + // suppression is only enabled if the next event is a paragraph. + suppress_paragraph = false; + match event { + Event::Start(tag) => { + match tag { + Tag::Paragraph => { + if !this_suppress_paragraph { + self.flush(); + } + } + Tag::Heading(n) => { + self.flush(); + if n == 1 { + let text = header_text(&mut self.parser)?; + self.push_to_line(&text.to_uppercase()); + self.hard_break(); + self.hard_break(); + } else if n == 2 { + let text = header_text(&mut self.parser)?; + self.push_to_line(&text.to_uppercase()); + self.flush(); + self.indent = 7; + } else { + let text = header_text(&mut self.parser)?; + self.push_indent((n as usize - 2) * 3); + self.push_to_line(&text); + self.flush(); + self.indent = (n as usize - 1) * 3 + 1; + } + } + Tag::BlockQuote => { + self.indent += 3; + } + Tag::CodeBlock(_kind) => { + self.flush(); + wrap_text = false; + self.indent += 4; + } + Tag::List(start) => list.push(start), + Tag::Item => { + self.flush(); + match list.last_mut().expect("item must have list start") { + // Ordered list. + Some(n) => { + self.push_indent(self.indent); + write!(self.line, "{}.", n)?; + *n += 1; + } + // Unordered list. + None => { + self.push_indent(self.indent); + self.push_to_line("o ") + } + } + self.indent += 3; + suppress_paragraph = true; + } + Tag::FootnoteDefinition(_label) => unimplemented!(), + Tag::Table(alignment) => { + assert!(self.table.alignment.is_empty()); + self.flush(); + self.table.alignment.extend(alignment); + let table = self.table.process(&mut self.parser, self.indent)?; + self.output.push_str(&table); + self.hard_break(); + self.table = Table::new(); + } + Tag::TableHead | Tag::TableRow | Tag::TableCell => { + bail!("unexpected table element") + } + Tag::Emphasis => {} + Tag::Strong => {} + // Strikethrough isn't usually supported for TTY. + Tag::Strikethrough => self.word.push_str("~~"), + Tag::Link(link_type, dest_url, _title) => { + if dest_url.starts_with('#') { + // In a man page, page-relative anchors don't + // have much meaning. + continue; + } + match link_type { + LinkType::Autolink | LinkType::Email => { + // The text is a copy of the URL, which is not needed. + match self.parser.next() { + Some((Event::Text(_), _range)) => {} + _ => bail!("expected text after autolink"), + } + } + LinkType::Inline + | LinkType::Reference + | LinkType::Collapsed + | LinkType::Shortcut => {} + // This is currently unused. This is only + // emitted with a broken link callback, but I + // felt it is too annoying to escape `[` in + // option descriptions. + LinkType::ReferenceUnknown + | LinkType::CollapsedUnknown + | LinkType::ShortcutUnknown => { + bail!( + "link with missing reference `{}` located at offset {}", + dest_url, + range.start + ); + } + } + } + Tag::Image(_link_type, _dest_url, _title) => { + bail!("images are not currently supported") + } + } + } + Event::End(tag) => match &tag { + Tag::Paragraph => { + self.flush(); + self.hard_break(); + } + Tag::Heading(_n) => {} + Tag::BlockQuote => { + self.indent -= 3; + } + Tag::CodeBlock(_kind) => { + self.hard_break(); + wrap_text = true; + self.indent -= 4; + } + Tag::List(_) => { + list.pop(); + } + Tag::Item => { + self.flush(); + self.indent -= 3; + self.hard_break(); + } + Tag::FootnoteDefinition(_label) => {} + Tag::Table(_) => {} + Tag::TableHead => {} + Tag::TableRow => {} + Tag::TableCell => {} + Tag::Emphasis => {} + Tag::Strong => {} + Tag::Strikethrough => self.word.push_str("~~"), + Tag::Link(link_type, dest_url, _title) => { + if dest_url.starts_with('#') { + continue; + } + match link_type { + LinkType::Autolink | LinkType::Email => {} + LinkType::Inline + | LinkType::Reference + | LinkType::Collapsed + | LinkType::Shortcut => self.flush_word(), + _ => { + panic!("unexpected tag {:?}", tag); + } + } + self.flush_word(); + write!(self.word, "<{}>", dest_url)?; + } + Tag::Image(_link_type, _dest_url, _title) => {} + }, + Event::Text(t) | Event::Code(t) => { + if wrap_text { + let chunks = split_chunks(&t); + for chunk in chunks { + if chunk == " " { + self.flush_word(); + } else { + self.word.push_str(chunk); + } + } + } else { + for line in t.lines() { + self.push_indent(self.indent); + self.push_to_line(line); + self.flush(); + } + } + } + Event::Html(t) => { + if t.starts_with("") { + in_cdata = false; + } else { + let trimmed = t.trim(); + if trimmed.is_empty() { + continue; + } + if trimmed == "
" { + self.hard_break(); + } else if trimmed.starts_with("
") { + let opts = unwrap(trimmed, "
", "
"); + self.push_indent(self.indent); + self.push_to_line(opts); + self.flush(); + } else if trimmed.starts_with("
") { + let mut def = String::new(); + while let Some((Event::Html(t), _range)) = self.parser.next() { + if t.starts_with("
") { + break; + } + def.push_str(&t); + } + let rendered = + TextRenderer::render(&def, self.url.clone(), self.indent + 4)?; + self.push_to_line(rendered.trim_end()); + self.flush(); + } else { + self.push_to_line(&t); + self.flush(); + } + } + } else { + self.push_to_line(&t); + self.flush(); + } + } + Event::FootnoteReference(_t) => {} + Event::SoftBreak => self.flush_word(), + Event::HardBreak => self.flush(), + Event::Rule => { + self.flush(); + self.push_indent(self.indent); + self.push_to_line(&"_".repeat(79 - self.indent * 2)); + self.flush(); + } + Event::TaskListMarker(_b) => unimplemented!(), + } + } + Ok(()) + } + + fn flush(&mut self) { + self.flush_word(); + if !self.line.is_empty() { + self.output.push_str(&self.line); + self.output.push('\n'); + self.line.clear(); + } + } + + fn hard_break(&mut self) { + self.flush(); + if !self.output.ends_with("\n\n") { + self.output.push('\n'); + } + } + + fn flush_word(&mut self) { + if self.word.is_empty() { + return; + } + if self.line.len() + self.word.len() >= 79 { + self.output.push_str(&self.line); + self.output.push('\n'); + self.line.clear(); + } + if self.line.is_empty() { + self.push_indent(self.indent); + self.line.push_str(&self.word); + } else { + self.line.push(' '); + self.line.push_str(&self.word); + } + self.word.clear(); + } + + fn push_indent(&mut self, indent: usize) { + for _ in 0..indent { + self.line.push(' '); + } + } + + fn push_to_line(&mut self, text: &str) { + self.flush_word(); + self.line.push_str(text); + } +} + +/// Splits the text on whitespace. +/// +/// Consecutive whitespace is collapsed to a single ' ', and is included as a +/// separate element in the result. +fn split_chunks(text: &str) -> Vec<&str> { + let mut result = Vec::new(); + let mut start = 0; + while start < text.len() { + match text[start..].find(' ') { + Some(i) => { + if i != 0 { + result.push(&text[start..start + i]); + } + result.push(" "); + // Skip past whitespace. + match text[start + i..].find(|c| c != ' ') { + Some(n) => { + start = start + i + n; + } + None => { + break; + } + } + } + None => { + result.push(&text[start..]); + break; + } + } + } + result +} + +struct Table { + alignment: Vec, + rows: Vec>, + row: Vec, + cell: String, +} + +impl Table { + fn new() -> Table { + Table { + alignment: Vec::new(), + rows: Vec::new(), + row: Vec::new(), + cell: String::new(), + } + } + + /// Processes table events and generates a text table. + fn process(&mut self, parser: &mut EventIter<'_>, indent: usize) -> Result { + while let Some((event, _range)) = parser.next() { + match event { + Event::Start(tag) => match tag { + Tag::TableHead + | Tag::TableRow + | Tag::TableCell + | Tag::Emphasis + | Tag::Strong => {} + Tag::Strikethrough => self.cell.push_str("~~"), + // Links not yet supported, they usually won't fit. + Tag::Link(_, _, _) => {} + _ => bail!("unexpected tag in table: {:?}", tag), + }, + Event::End(tag) => match tag { + Tag::Table(_) => return self.render(indent), + Tag::TableCell => { + let cell = mem::replace(&mut self.cell, String::new()); + self.row.push(cell); + } + Tag::TableHead | Tag::TableRow => { + let row = mem::replace(&mut self.row, Vec::new()); + self.rows.push(row); + } + Tag::Strikethrough => self.cell.push_str("~~"), + _ => {} + }, + Event::Text(t) | Event::Code(t) => { + self.cell.push_str(&t); + } + Event::Html(t) => bail!("html unsupported in tables: {:?}", t), + _ => bail!("unexpected event in table: {:?}", event), + } + } + bail!("table end not reached"); + } + + fn render(&self, indent: usize) -> Result { + // This is an extremely primitive layout routine. + // First compute the potential maximum width of each cell. + // 2 for 1 space margin on left and right. + let width_acc = vec![2; self.alignment.len()]; + let mut col_widths = self + .rows + .iter() + .map(|row| row.iter().map(|cell| cell.len())) + .fold(width_acc, |mut acc, row| { + acc.iter_mut() + .zip(row) + // +3 for left/right margin and | symbol + .for_each(|(a, b)| *a = (*a).max(b + 3)); + acc + }); + // Shrink each column until it fits the total width, proportional to + // the columns total percent width. + let max_width = 78 - indent; + // Include total len for | characters, and +1 for final |. + let total_width = col_widths.iter().sum::() + col_widths.len() + 1; + if total_width > max_width { + let to_shrink = total_width - max_width; + // Compute percentage widths, and shrink each column based on its + // total percentage. + for width in &mut col_widths { + let percent = *width as f64 / total_width as f64; + *width -= (to_shrink as f64 * percent).ceil() as usize; + } + } + // Start rendering. + let mut result = String::new(); + + // Draw the horizontal line separating each row. + let mut row_line = String::new(); + row_line.push_str(&" ".repeat(indent)); + row_line.push('+'); + let lines = col_widths + .iter() + .map(|width| "-".repeat(*width)) + .collect::>(); + row_line.push_str(&lines.join("+")); + row_line.push('+'); + row_line.push('\n'); + + // Draw top of the table. + result.push_str(&row_line); + // Draw each row. + for row in &self.rows { + // Word-wrap and fill each column as needed. + let filled = fill_row(row, &col_widths, &self.alignment); + // Need to transpose the cells across rows for cells that span + // multiple rows. + let height = filled.iter().map(|c| c.len()).max().unwrap(); + for row_i in 0..height { + result.push_str(&" ".repeat(indent)); + result.push('|'); + for filled_row in &filled { + let cell = &filled_row[row_i]; + result.push_str(cell); + result.push('|'); + } + result.push('\n'); + } + result.push_str(&row_line); + } + Ok(result) + } +} + +/// Formats a row, filling cells with spaces and word-wrapping text. +/// +/// Returns a vec of cells, where each cell is split into multiple lines. +fn fill_row(row: &[String], col_widths: &[usize], alignment: &[Alignment]) -> Vec> { + let mut cell_lines = row + .iter() + .zip(col_widths) + .zip(alignment) + .map(|((cell, width), alignment)| fill_cell(cell, *width - 2, *alignment)) + .collect::>(); + // Fill each cell to match the maximum vertical height of the tallest cell. + let max_lines = cell_lines.iter().map(|cell| cell.len()).max().unwrap(); + for (cell, width) in cell_lines.iter_mut().zip(col_widths) { + if cell.len() < max_lines { + cell.extend(std::iter::repeat(" ".repeat(*width)).take(max_lines - cell.len())); + } + } + cell_lines +} + +/// Formats a cell. Word-wraps based on width, and adjusts based on alignment. +/// +/// Returns a vec of lines for the cell. +fn fill_cell(text: &str, width: usize, alignment: Alignment) -> Vec { + let fill_width = |text: &str| match alignment { + Alignment::None | Alignment::Left => format!(" {: format!(" {:^width$} ", text, width = width), + Alignment::Right => format!(" {:>width$} ", text, width = width), + }; + if text.len() < width { + // No wrapping necessary, just format. + vec![fill_width(text)] + } else { + // Word-wrap the cell. + let mut result = Vec::new(); + let mut line = String::new(); + for word in text.split_whitespace() { + if line.len() + word.len() >= width { + // todo: word.len() > width + result.push(fill_width(&line)); + line.clear(); + } + if line.is_empty() { + line.push_str(word); + } else { + line.push(' '); + line.push_str(&word); + } + } + if !line.is_empty() { + result.push(fill_width(&line)); + } + + result + } +} diff --git a/crates/mdman/src/hbs.rs b/crates/mdman/src/hbs.rs new file mode 100644 index 00000000000..a8cbae94ad8 --- /dev/null +++ b/crates/mdman/src/hbs.rs @@ -0,0 +1,217 @@ +//! Handlebars template processing. + +use crate::format::Formatter; +use anyhow::Error; +use handlebars::{ + handlebars_helper, Context, Decorator, Handlebars, Helper, HelperDef, HelperResult, Output, + RenderContext, RenderError, Renderable, +}; +use std::collections::HashMap; +use std::convert::TryFrom; +use std::path::Path; + +type FormatterRef<'a> = &'a (dyn Formatter + Send + Sync); + +/// Processes the handlebars template at the given file. +pub fn expand(file: &Path, formatter: FormatterRef) -> Result { + let mut handlebars = Handlebars::new(); + handlebars.set_strict_mode(true); + handlebars.register_helper("lower", Box::new(lower)); + handlebars.register_helper("options", Box::new(OptionsHelper { formatter })); + handlebars.register_helper("option", Box::new(OptionHelper { formatter })); + handlebars.register_helper("man", Box::new(ManLinkHelper { formatter })); + handlebars.register_decorator("set", Box::new(set_decorator)); + handlebars.register_template_file("template", file)?; + let includes = file.parent().unwrap().join("includes"); + handlebars.register_templates_directory(".md", includes)?; + let mut data: HashMap = HashMap::new(); + let man_name = file + .file_stem() + .expect("expected filename") + .to_str() + .expect("utf8 filename") + .to_string(); + data.insert("man_name".to_string(), man_name); + let expanded = handlebars.render("template", &data)?; + Ok(expanded) +} + +/// Helper for `{{#options}}` block. +struct OptionsHelper<'a> { + formatter: FormatterRef<'a>, +} + +impl HelperDef for OptionsHelper<'_> { + fn call<'reg: 'rc, 'rc>( + &self, + h: &Helper<'reg, 'rc>, + r: &'reg Handlebars<'reg>, + ctx: &'rc Context, + rc: &mut RenderContext<'reg, 'rc>, + out: &mut dyn Output, + ) -> HelperResult { + if in_options(rc) { + return Err(RenderError::new("options blocks cannot be nested")); + } + // Prevent nested {{#options}}. + set_in_context(rc, "__MDMAN_IN_OPTIONS", serde_json::Value::Bool(true)); + let s = self.formatter.render_options_start(); + out.write(&s)?; + let t = match h.template() { + Some(t) => t, + None => return Err(RenderError::new("options block must not be empty")), + }; + let block = t.renders(r, ctx, rc)?; + out.write(&block)?; + + let s = self.formatter.render_options_end(); + out.write(&s)?; + remove_from_context(rc, "__MDMAN_IN_OPTIONS"); + Ok(()) + } +} + +/// Whether or not the context is currently inside a `{{#options}}` block. +fn in_options(rc: &RenderContext<'_, '_>) -> bool { + rc.context() + .map_or(false, |ctx| ctx.data().get("__MDMAN_IN_OPTIONS").is_some()) +} + +/// Helper for `{{#option}}` block. +struct OptionHelper<'a> { + formatter: FormatterRef<'a>, +} + +impl HelperDef for OptionHelper<'_> { + fn call<'reg: 'rc, 'rc>( + &self, + h: &Helper<'reg, 'rc>, + r: &'reg Handlebars<'reg>, + ctx: &'rc Context, + rc: &mut RenderContext<'reg, 'rc>, + out: &mut dyn Output, + ) -> HelperResult { + if !in_options(rc) { + return Err(RenderError::new("option must be in options block")); + } + let params = h.params(); + if params.is_empty() { + return Err(RenderError::new( + "option block must have at least one param", + )); + } + // Convert params to strings. + let params = params + .iter() + .map(|param| { + param + .value() + .as_str() + .ok_or_else(|| RenderError::new("option params must be strings")) + }) + .collect::, RenderError>>()?; + let t = match h.template() { + Some(t) => t, + None => return Err(RenderError::new("option block must not be empty")), + }; + // Render the block. + let block = t.renders(r, ctx, rc)?; + + // Get the name of this page. + let man_name = ctx + .data() + .get("man_name") + .expect("expected man_name in context") + .as_str() + .expect("expect man_name str"); + + // Ask the formatter to convert this option to its format. + let option = self + .formatter + .render_option(¶ms, &block, man_name) + .map_err(|e| RenderError::new(format!("option render failed: {}", e)))?; + out.write(&option)?; + Ok(()) + } +} + +/// Helper for `{{man name section}}` expression. +struct ManLinkHelper<'a> { + formatter: FormatterRef<'a>, +} + +impl HelperDef for ManLinkHelper<'_> { + fn call<'reg: 'rc, 'rc>( + &self, + h: &Helper<'reg, 'rc>, + _r: &'reg Handlebars<'reg>, + _ctx: &'rc Context, + _rc: &mut RenderContext<'reg, 'rc>, + out: &mut dyn Output, + ) -> HelperResult { + let params = h.params(); + if params.len() != 2 { + return Err(RenderError::new("{{man}} must have two arguments")); + } + let name = params[0] + .value() + .as_str() + .ok_or_else(|| RenderError::new("man link name must be a string"))?; + let section = params[1] + .value() + .as_u64() + .ok_or_else(|| RenderError::new("man link section must be an integer"))?; + let section = + u8::try_from(section).map_err(|_e| RenderError::new("section number too large"))?; + let link = self + .formatter + .linkify_man_to_md(name, section) + .map_err(|e| RenderError::new(format!("failed to linkify man: {}", e)))?; + out.write(&link)?; + Ok(()) + } +} + +/// `{{*set var=value}}` decorator. +/// +/// This sets a variable to a value within the template context. +fn set_decorator( + d: &Decorator, + _: &Handlebars, + _ctx: &Context, + rc: &mut RenderContext, +) -> Result<(), RenderError> { + let data_to_set = d.hash(); + for (k, v) in data_to_set { + set_in_context(rc, k, v.value().clone()); + } + Ok(()) +} + +/// Sets a variable to a value within the context. +fn set_in_context(rc: &mut RenderContext, key: &str, value: serde_json::Value) { + let mut ctx = match rc.context() { + Some(c) => (*c).clone(), + None => Context::wraps(serde_json::Value::Object(serde_json::Map::new())).unwrap(), + }; + if let serde_json::Value::Object(m) = ctx.data_mut() { + m.insert(key.to_string(), value); + rc.set_context(ctx); + } else { + panic!("expected object in context"); + } +} + +/// Removes a variable from the context. +fn remove_from_context(rc: &mut RenderContext, key: &str) { + let ctx = rc.context().expect("cannot remove from null context"); + let mut ctx = (*ctx).clone(); + if let serde_json::Value::Object(m) = ctx.data_mut() { + m.remove(key); + rc.set_context(ctx); + } else { + panic!("expected object in context"); + } +} + +handlebars_helper!(lower: |s: str| s.to_lowercase()); diff --git a/crates/mdman/src/lib.rs b/crates/mdman/src/lib.rs new file mode 100644 index 00000000000..c21b9a027cc --- /dev/null +++ b/crates/mdman/src/lib.rs @@ -0,0 +1,118 @@ +//! mdman markdown to man converter. + +use anyhow::{bail, Context, Error}; +use pulldown_cmark::{CowStr, Event, LinkType, Options, Parser, Tag}; +use std::collections::HashMap; +use std::fs; +use std::io::{self, BufRead}; +use std::ops::Range; +use std::path::Path; +use url::Url; + +mod format; +mod hbs; +mod util; + +use format::Formatter; + +/// Mapping of `(name, section)` of a man page to a URL. +pub type ManMap = HashMap<(String, u8), String>; + +/// A man section. +pub type Section = u8; + +/// The output formats supported by mdman. +#[derive(Copy, Clone)] +pub enum Format { + Man, + Md, + Text, +} + +impl Format { + /// The filename extension for the format. + pub fn extension(&self, section: Section) -> String { + match self { + Format::Man => section.to_string(), + Format::Md => "md".to_string(), + Format::Text => "txt".to_string(), + } + } +} + +/// Converts the handlebars markdown file at the given path into the given +/// format, returning the translated result. +pub fn convert( + file: &Path, + format: Format, + url: Option, + man_map: ManMap, +) -> Result { + let formatter: Box = match format { + Format::Man => Box::new(format::man::ManFormatter::new(url)), + Format::Md => Box::new(format::md::MdFormatter::new(url, man_map)), + Format::Text => Box::new(format::text::TextFormatter::new(url)), + }; + let expanded = hbs::expand(file, &*formatter)?; + formatter.render(&expanded) +} + +/// Pulldown-cmark iterator yielding an `(event, range)` tuple. +type EventIter<'a> = Box, Range)> + 'a>; + +/// Creates a new markdown parser with the given input. +pub(crate) fn md_parser(input: &str, url: Option) -> EventIter { + let mut options = Options::empty(); + options.insert(Options::ENABLE_TABLES); + options.insert(Options::ENABLE_FOOTNOTES); + options.insert(Options::ENABLE_STRIKETHROUGH); + let parser = Parser::new_ext(input, options); + let parser = parser.into_offset_iter(); + // Translate all links to include the base url. + let parser = parser.map(move |(event, range)| match event { + Event::Start(Tag::Link(lt, dest_url, title)) if !matches!(lt, LinkType::Email) => ( + Event::Start(Tag::Link(lt, join_url(url.as_ref(), dest_url), title)), + range, + ), + Event::End(Tag::Link(lt, dest_url, title)) if !matches!(lt, LinkType::Email) => ( + Event::End(Tag::Link(lt, join_url(url.as_ref(), dest_url), title)), + range, + ), + _ => (event, range), + }); + Box::new(parser) +} + +fn join_url<'a>(base: Option<&Url>, dest: CowStr<'a>) -> CowStr<'a> { + match base { + Some(base_url) => { + // Absolute URL or page-relative anchor doesn't need to be translated. + if dest.contains(':') || dest.starts_with('#') { + dest + } else { + let joined = base_url.join(&dest).unwrap_or_else(|e| { + panic!("failed to join URL `{}` to `{}`: {}", dest, base_url, e) + }); + joined.into_string().into() + } + } + None => dest, + } +} + +pub fn extract_section(file: &Path) -> Result { + let f = fs::File::open(file).with_context(|| format!("could not open `{}`", file.display()))?; + let mut f = io::BufReader::new(f); + let mut line = String::new(); + f.read_line(&mut line)?; + if !line.starts_with("# ") { + bail!("expected input file to start with # header"); + } + let (_name, section) = util::parse_name_and_section(&line[2..].trim()).with_context(|| { + format!( + "expected input file to have header with the format `# command-name(1)`, found: `{}`", + line + ) + })?; + Ok(section) +} diff --git a/crates/mdman/src/main.rs b/crates/mdman/src/main.rs new file mode 100644 index 00000000000..2bdf96d7230 --- /dev/null +++ b/crates/mdman/src/main.rs @@ -0,0 +1,133 @@ +use anyhow::{bail, format_err, Context, Error}; +use mdman::{Format, ManMap}; +use std::collections::HashMap; +use std::path::{Path, PathBuf}; +use url::Url; + +/// Command-line options. +struct Options { + format: Format, + output_dir: PathBuf, + sources: Vec, + url: Option, + man_map: ManMap, +} + +fn main() { + if let Err(e) = run() { + eprintln!("error: {}", e); + for cause in e.chain().skip(1) { + eprintln!("\nCaused by:"); + for line in cause.to_string().lines() { + if line.is_empty() { + eprintln!(); + } else { + eprintln!(" {}", line); + } + } + } + std::process::exit(1); + } +} + +fn run() -> Result<(), Error> { + let opts = process_args()?; + if !opts.output_dir.exists() { + std::fs::create_dir_all(&opts.output_dir).with_context(|| { + format!( + "failed to create output directory {}", + opts.output_dir.display() + ) + })?; + } + for source in &opts.sources { + let section = mdman::extract_section(source)?; + let filename = + Path::new(source.file_name().unwrap()).with_extension(opts.format.extension(section)); + let out_path = opts.output_dir.join(filename); + if same_file::is_same_file(source, &out_path).unwrap_or(false) { + bail!("cannot output to the same file as the source"); + } + println!("Converting {} -> {}", source.display(), out_path.display()); + let result = mdman::convert(&source, opts.format, opts.url.clone(), opts.man_map.clone()) + .with_context(|| format!("failed to translate {}", source.display()))?; + + std::fs::write(out_path, result)?; + } + Ok(()) +} + +fn process_args() -> Result { + let mut format = None; + let mut output = None; + let mut url = None; + let mut man_map: ManMap = HashMap::new(); + let mut sources = Vec::new(); + let mut args = std::env::args().skip(1); + while let Some(arg) = args.next() { + match arg.as_str() { + "-t" => { + format = match args.next().as_deref() { + Some("man") => Some(Format::Man), + Some("md") => Some(Format::Md), + Some("txt") => Some(Format::Text), + Some(s) => bail!("unknown output format: {}", s), + None => bail!("-t requires a value (man, md, txt)"), + }; + } + "-o" => { + output = match args.next() { + Some(s) => Some(PathBuf::from(s)), + None => bail!("-o requires a value"), + }; + } + "--url" => { + url = match args.next() { + Some(s) => { + let url = Url::parse(&s) + .with_context(|| format!("could not convert `{}` to a url", s))?; + if !url.path().ends_with('/') { + bail!("url `{}` should end with a /", url); + } + Some(url) + } + None => bail!("--url requires a value"), + } + } + "--man" => { + let man = args + .next() + .ok_or_else(|| format_err!("--man requires a value"))?; + let parts: Vec<_> = man.splitn(2, '=').collect(); + let key_parts: Vec<_> = parts[0].splitn(2, ':').collect(); + if parts.len() != 2 || key_parts.len() != 2 { + bail!("--man expected value with form name:1=link"); + } + let section: u8 = key_parts[1].parse().with_context(|| { + format!("expected unsigned integer for section, got `{}`", parts[1]) + })?; + man_map.insert((key_parts[0].to_string(), section), parts[1].to_string()); + } + s => { + sources.push(PathBuf::from(s)); + } + } + } + if format.is_none() { + bail!("-t must be specified (man, md, txt)"); + } + if output.is_none() { + bail!("-o must be specified (output directory)"); + } + if sources.is_empty() { + bail!("at least one source must be specified"); + } + let opts = Options { + format: format.unwrap(), + output_dir: output.unwrap(), + sources, + url, + man_map, + }; + Ok(opts) +} diff --git a/crates/mdman/src/util.rs b/crates/mdman/src/util.rs new file mode 100644 index 00000000000..e85f22093a7 --- /dev/null +++ b/crates/mdman/src/util.rs @@ -0,0 +1,44 @@ +///! General utilities. +use crate::EventIter; +use anyhow::{bail, format_err, Context, Error}; +use pulldown_cmark::{CowStr, Event, Tag}; + +/// Splits the text `foo(1)` into "foo" and `1`. +pub fn parse_name_and_section(text: &str) -> Result<(&str, u8), Error> { + let mut i = text.split_terminator(&['(', ')'][..]); + let name = i + .next() + .ok_or_else(|| format_err!("man reference must have a name"))?; + let section = i + .next() + .ok_or_else(|| format_err!("man reference must have a section such as mycommand(1)"))?; + if let Some(s) = i.next() { + bail!( + "man reference must have the form mycommand(1), got extra part `{}`", + s + ); + } + let section: u8 = section + .parse() + .with_context(|| format!("section must be a number, got {}", section))?; + Ok((name, section)) +} + +/// Extracts the text from a header after Tag::Heading has been received. +pub fn header_text<'e>(parser: &mut EventIter<'e>) -> Result, Error> { + let text = match parser.next() { + Some((Event::Text(t), _range)) => t, + e => bail!("expected plain text in man header, got {:?}", e), + }; + match parser.next() { + Some((Event::End(Tag::Heading(_)), _range)) => { + return Ok(text); + } + e => bail!("expected plain text in man header, got {:?}", e), + } +} + +/// Removes tags from the front and back of a string. +pub fn unwrap<'t>(text: &'t str, front: &str, back: &str) -> &'t str { + text.trim().trim_start_matches(front).trim_end_matches(back) +} diff --git a/crates/mdman/tests/compare.rs b/crates/mdman/tests/compare.rs new file mode 100644 index 00000000000..4a081d439b2 --- /dev/null +++ b/crates/mdman/tests/compare.rs @@ -0,0 +1,46 @@ +//! Compares input to expected output. +//! +//! Use the MDMAN_BLESS environment variable to automatically update the +//! expected output. + +use mdman::{Format, ManMap}; +use pretty_assertions::assert_eq; +use std::path::PathBuf; +use url::Url; + +fn run(name: &str) { + let input = PathBuf::from(format!("tests/compare/{}.md", name)); + let url = Some(Url::parse("https://example.org/").unwrap()); + let mut map = ManMap::new(); + map.insert( + ("other-cmd".to_string(), 1), + "https://example.org/commands/other-cmd.html".to_string(), + ); + + for &format in &[Format::Man, Format::Md, Format::Text] { + let section = mdman::extract_section(&input).unwrap(); + let result = mdman::convert(&input, format, url.clone(), map.clone()).unwrap(); + let expected_path = format!( + "tests/compare/expected/{}.{}", + name, + format.extension(section) + ); + if std::env::var("MDMAN_BLESS").is_ok() { + std::fs::write(&expected_path, result).unwrap(); + } else { + let expected = std::fs::read_to_string(&expected_path).unwrap(); + assert_eq!(expected, result); + } + } +} + +macro_rules! test( ($name:ident) => ( + #[test] + fn $name() { run(stringify!($name)); } +) ); + +test!(formatting); +test!(links); +test!(options); +test!(tables); +test!(vars); diff --git a/crates/mdman/tests/compare/expected/formatting.1 b/crates/mdman/tests/compare/expected/formatting.1 new file mode 100644 index 00000000000..dbd24526289 --- /dev/null +++ b/crates/mdman/tests/compare/expected/formatting.1 @@ -0,0 +1,118 @@ +'\" t +.TH "FORMATTING" "1" +.nh +.ad l +.ss \n[.ss] 0 +.sp +This is \fBnested \f(BIformatting\fB \fBtext\fB\fR\&. +.SH "SECOND HEADING" +Some text at second level. +.SS "Third heading" +Some text at third level. +.SS "Fourth heading" +Some text at fourth level. +.SH "Quotes and blocks." +Here are some quotes and blocks. +.RS 3 +.ll -5 +.sp +This is a block quote. Ambidextrously koala apart that prudent blindly alas +far amid dear goodness turgid so exact inside oh and alas much fanciful that +dark on spoon\-fed adequately insolent walking crud. +.br +.RE +.ll +.sp +.RS 4 +.nf +This is a code block. Groundhog watchfully sudden firefly some self\-consciously hotly jeepers satanic after that this parrot this at virtuous +some mocking the leaned jeez nightingale as much mallard so because jeez +turned dear crud grizzly strenuously. + + Indented and should be unmodified. +.fi +.RE +.sp +.RS 4 +.nf +This is an indented code block. Egregiously yikes animatedly since outside beseechingly a badger hey shakily giraffe a one wow one this +goodness regarding reindeer so astride before. + + Doubly indented +.fi +.RE +.SH "Lists" +.sp +.RS 4 +\h'-04' 1.\h'+01'Ordered list +.sp +.RS 4 +\h'-04'\(bu\h'+02'Unordered list +.sp +With a second paragraph inside it +.sp +.RS 4 +\h'-04' 1.\h'+01'Inner ordered list +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Another +.RE +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Eggs +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Milk +.sp +.RS 4 +\h'-04' 5.\h'+01'Don't start at one. +.RE +.sp +.RS 4 +\h'-04' 6.\h'+01'tamarind +.RE +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Second element +.RE +.sp +.RS 4 +\h'-04' 3.\h'+01'Third element +.RE +.SH "Breaks" +This has a +.br +hard break in it +and a soft one. +.SH "Horizontal rule" +This should contain a line: +\l'\n(.lu' +.sp +Nice! +.SH "Strange characters" +Handles escaping for characters +.sp +\&.dot at the start of a line. +.sp +\(rsfBnot really troff +.sp +Various characters \(rs \- \[en] \[em] \- | | ` +.sp +.RS 4 +.nf +tree +`\-\- example + |\-\- salamander + | |\-\- honey + | `\-\- some + |\-\- fancifully + `\-\- trout +.fi +.RE +.sp +\ \ \ \ non\-breaking space. diff --git a/crates/mdman/tests/compare/expected/formatting.md b/crates/mdman/tests/compare/expected/formatting.md new file mode 100644 index 00000000000..6909bd44343 --- /dev/null +++ b/crates/mdman/tests/compare/expected/formatting.md @@ -0,0 +1,94 @@ +# formatting(1) + +This is **nested _formatting_ `text`**. + +## SECOND HEADING + +Some text at second level. + +### Third heading + +Some text at third level. + +#### Fourth heading + +Some text at fourth level. + +## Quotes and blocks. + +Here are some quotes and blocks. + +> This is a block quote. Ambidextrously koala apart that prudent blindly alas +> far amid dear goodness turgid so exact inside oh and alas much fanciful that +> dark on spoon-fed adequately insolent walking crud. + +``` +This is a code block. Groundhog watchfully sudden firefly some self-consciously hotly jeepers satanic after that this parrot this at virtuous +some mocking the leaned jeez nightingale as much mallard so because jeez +turned dear crud grizzly strenuously. + + Indented and should be unmodified. +``` + + This is an indented code block. Egregiously yikes animatedly since outside beseechingly a badger hey shakily giraffe a one wow one this + goodness regarding reindeer so astride before. + + Doubly indented + +## Lists + +1. Ordered list + + * Unordered list + + With a second paragraph inside it + + 1. Inner ordered list + + 1. Another + + * Eggs + + * Milk + 5. Don't start at one. + 6. tamarind + +1. Second element + +1. Third element + +## Breaks + +This has a\ +hard break in it +and a soft one. + +## Horizontal rule + +This should contain a line: + +--- + +Nice! + +## Strange characters + +Handles escaping for characters + +.dot at the start of a line. + +\fBnot really troff + +Various characters \ - – — ─ │ ├ └ + +``` +tree +└── example + ├── salamander + │ ├── honey + │ └── some + ├── fancifully + └── trout +``` + +    non-breaking space. diff --git a/crates/mdman/tests/compare/expected/formatting.txt b/crates/mdman/tests/compare/expected/formatting.txt new file mode 100644 index 00000000000..865b714b630 --- /dev/null +++ b/crates/mdman/tests/compare/expected/formatting.txt @@ -0,0 +1,84 @@ +FORMATTING(1) + +This is nested formatting text. + +SECOND HEADING + Some text at second level. + + Third heading + Some text at third level. + + Fourth heading + Some text at fourth level. + +QUOTES AND BLOCKS. + Here are some quotes and blocks. + + This is a block quote. Ambidextrously koala apart that prudent + blindly alas far amid dear goodness turgid so exact inside oh and + alas much fanciful that dark on spoon-fed adequately insolent walking + crud. + + This is a code block. Groundhog watchfully sudden firefly some self-consciously hotly jeepers satanic after that this parrot this at virtuous + some mocking the leaned jeez nightingale as much mallard so because jeez + turned dear crud grizzly strenuously. + + Indented and should be unmodified. + + This is an indented code block. Egregiously yikes animatedly since outside beseechingly a badger hey shakily giraffe a one wow one this + goodness regarding reindeer so astride before. + + Doubly indented + +LISTS + 1. Ordered list + + o Unordered list + + With a second paragraph inside it + + 1. Inner ordered list + + 2. Another + + o Eggs + + o Milk + + 5. Don't start at one. + + 6. tamarind + + 2. Second element + + 3. Third element + +BREAKS + This has a + hard break in it and a soft one. + +HORIZONTAL RULE + This should contain a line: + + _________________________________________________________________ + Nice! + +STRANGE CHARACTERS + Handles escaping for characters + + .dot at the start of a line. + + \fBnot really troff + + Various characters \ - – — ─ │ ├ └ + + tree + └── example + ├── salamander + │ ├── honey + │ └── some + ├── fancifully + └── trout + +     non-breaking space. + diff --git a/crates/mdman/tests/compare/expected/links.1 b/crates/mdman/tests/compare/expected/links.1 new file mode 100644 index 00000000000..51520c0a3f6 --- /dev/null +++ b/crates/mdman/tests/compare/expected/links.1 @@ -0,0 +1,31 @@ +'\" t +.TH "LINKS" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +links \- Test of different link kinds +.SH "DESCRIPTION" +Inline link: \fIinline link\fR +.sp +Reference link: \fIthis is a link\fR +.sp +Collapsed: \fIcollapsed\fR +.sp +Shortcut: \fIshortcut\fR +.sp +Autolink: +.sp +Email: +.sp +Relative link: \fIrelative link\fR +.sp +Collapsed unknown: [collapsed unknown][] +.sp +Reference unknown: [foo][unknown] +.sp +Shortcut unknown: [shortcut unknown] +.sp +\fBother\-cmd\fR(1) +.sp +\fBlocal\-cmd\fR(1) diff --git a/crates/mdman/tests/compare/expected/links.md b/crates/mdman/tests/compare/expected/links.md new file mode 100644 index 00000000000..b6b71d6c013 --- /dev/null +++ b/crates/mdman/tests/compare/expected/links.md @@ -0,0 +1,35 @@ +# links(1) + +## NAME + +links - Test of different link kinds + +## DESCRIPTION + +Inline link: [inline link](https://example.com/inline) + +Reference link: [this is a link][bar] + +Collapsed: [collapsed][] + +Shortcut: [shortcut] + +Autolink: + +Email: + +Relative link: [relative link](foo/bar.html) + +Collapsed unknown: [collapsed unknown][] + +Reference unknown: [foo][unknown] + +Shortcut unknown: [shortcut unknown] + +[other-cmd(1)](https://example.org/commands/other-cmd.html) + +[local-cmd(1)](local-cmd.md) + +[bar]: https://example.com/bar +[collapsed]: https://example.com/collapsed +[shortcut]: https://example.com/shortcut diff --git a/crates/mdman/tests/compare/expected/links.txt b/crates/mdman/tests/compare/expected/links.txt new file mode 100644 index 00000000000..6475c037632 --- /dev/null +++ b/crates/mdman/tests/compare/expected/links.txt @@ -0,0 +1,30 @@ +LINKS(1) + +NAME + links - Test of different link kinds + +DESCRIPTION + Inline link: inline link + + Reference link: this is a link + + Collapsed: collapsed + + Shortcut: shortcut + + Autolink: + + Email: + + Relative link: relative link + + Collapsed unknown: [collapsed unknown][] + + Reference unknown: [foo][unknown] + + Shortcut unknown: [shortcut unknown] + + other-cmd(1) + + local-cmd(1) + diff --git a/crates/mdman/tests/compare/expected/options.1 b/crates/mdman/tests/compare/expected/options.1 new file mode 100644 index 00000000000..2d75cd25e9d --- /dev/null +++ b/crates/mdman/tests/compare/expected/options.1 @@ -0,0 +1,94 @@ +'\" t +.TH "MY\-COMMAND" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "NAME" +my\-command \- A brief description +.SH "SYNOPSIS" +\fBmy\-command\fR [\fB\-\-abc\fR | \fB\-\-xyz\fR] \fIname\fR +.br +\fBmy\-command\fR [\fB\-f\fR \fIfile\fR] +.br +\fBmy\-command\fR (\fB\-m\fR | \fB\-M\fR) [\fIoldbranch\fR] \fInewbranch\fR +.br +\fBmy\-command\fR (\fB\-d\fR | \fB\-D\fR) [\fB\-r\fR] \fIbranchname\fR\&... +.SH "DESCRIPTION" +A description of the command. +.sp +.RS 4 +\h'-04'\(bu\h'+02'One +.sp +.RS 4 +\h'-04'\(bu\h'+02'Sub one +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Sub two +.RE +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Two +.RE +.sp +.RS 4 +\h'-04'\(bu\h'+02'Three +.RE +.SH "OPTIONS" +.SS "Command options" +.sp +\fB\-\-foo\-bar\fR +.RS 4 +Demo \fIemphasis\fR, \fBstrong\fR, ~~strike~~ +.RE +.sp +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR +.RS 4 +This has multiple flags. +.RE +.sp +\fInamed\-arg...\fR +.RS 4 +A named argument. +.RE +.SS "Common Options" +.sp +\fB@\fR\fIfilename\fR +.RS 4 +Load from filename. +.RE +.sp +\fB\-\-foo\fR [\fIbar\fR] +.RS 4 +Flag with optional value. +.RE +.sp +\fB\-\-foo\fR[\fB=\fR\fIbar\fR] +.RS 4 +Alternate syntax for optional value (with required = for disambiguation). +.RE +.SH "EXAMPLES" +.sp +.RS 4 +\h'-04' 1.\h'+01'An example +.sp +.RS 4 +.nf +my\-command \-\-abc +.fi +.RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Another example +.sp +.RS 4 +.nf +my\-command \-\-xyz +.fi +.RE +.RE +.SH "SEE ALSO" +\fBother\-command\fR(1) \fBabc\fR(7) diff --git a/crates/mdman/tests/compare/expected/options.md b/crates/mdman/tests/compare/expected/options.md new file mode 100644 index 00000000000..3c08de57f1d --- /dev/null +++ b/crates/mdman/tests/compare/expected/options.md @@ -0,0 +1,77 @@ +# my-command(1) + +## NAME + +my-command - A brief description + +## SYNOPSIS + +`my-command` [`--abc` | `--xyz`] _name_\ +`my-command` [`-f` _file_]\ +`my-command` (`-m` | `-M`) [_oldbranch_] _newbranch_\ +`my-command` (`-d` | `-D`) [`-r`] _branchname_... + +## DESCRIPTION + +A description of the command. + +* One + * Sub one + * Sub two +* Two +* Three + + +## OPTIONS + +### Command options + +
+ +
--foo-bar
+
Demo emphasis, strong, strike
+ + +
-p spec
+
--package spec
+
This has multiple flags.
+ + +
named-arg...
+
A named argument.
+ + +
+ +### Common Options + +
+
@filename
+
Load from filename.
+ + +
--foo [bar]
+
Flag with optional value.
+ + +
--foo[=bar]
+
Alternate syntax for optional value (with required = for disambiguation).
+ + +
+ + +## EXAMPLES + +1. An example + + ``` + my-command --abc + ``` + +1. Another example + + my-command --xyz + +## SEE ALSO +[other-command(1)](other-command.md) [abc(7)](abc.md) diff --git a/crates/mdman/tests/compare/expected/options.txt b/crates/mdman/tests/compare/expected/options.txt new file mode 100644 index 00000000000..32ccfd249b8 --- /dev/null +++ b/crates/mdman/tests/compare/expected/options.txt @@ -0,0 +1,57 @@ +MY-COMMAND(1) + +NAME + my-command - A brief description + +SYNOPSIS + my-command [--abc | --xyz] name + my-command [-f file] + my-command (-m | -M) [oldbranch] newbranch + my-command (-d | -D) [-r] branchname... + +DESCRIPTION + A description of the command. + + o One + o Sub one + + o Sub two + + o Two + + o Three + +OPTIONS + Command options + --foo-bar + Demo emphasis, strong, ~~strike~~ + + -p spec, --package spec + This has multiple flags. + + named-arg... + A named argument. + + Common Options + @filename + Load from filename. + + --foo [bar] + Flag with optional value. + + --foo[=bar] + Alternate syntax for optional value (with required = for + disambiguation). + +EXAMPLES + 1. An example + + my-command --abc + + 2. Another example + + my-command --xyz + +SEE ALSO + other-command(1) abc(7) + diff --git a/crates/mdman/tests/compare/expected/tables.1 b/crates/mdman/tests/compare/expected/tables.1 new file mode 100644 index 00000000000..7175a3e85b8 --- /dev/null +++ b/crates/mdman/tests/compare/expected/tables.1 @@ -0,0 +1,108 @@ +'\" t +.TH "TABLES" "1" +.nh +.ad l +.ss \n[.ss] 0 +.SH "DESCRIPTION" +Testing tables. + +.TS +allbox tab(:); +lt. +T{ +Single col +T} +T{ +Hi! :) +T} +.TE +.sp + +.TS +allbox tab(:); +lt lt lt. +T{ +Header content +T}:T{ +With \fBformat\fR \fItext\fR +T}:T{ +Another column +T} +T{ +Some data +T}:T{ +More data +T}:T{ + +T} +T{ +Extra long amount of text within a column +T}:T{ +hi +T}:T{ +there +T} +.TE +.sp + +.TS +allbox tab(:); +lt ct rt. +T{ +Left aligned +T}:T{ +Center aligned +T}:T{ +Right aligned +T} +T{ +abc +T}:T{ +def +T}:T{ +ghi +T} +.TE +.sp + +.TS +allbox tab(:); +lt ct rt. +T{ +Left aligned +T}:T{ +Center aligned +T}:T{ +Right aligned +T} +T{ +X +T}:T{ +X +T}:T{ +X +T} +T{ +Extra long text 123456789012 with mixed widths. +T}:T{ +Extra long text 123456789012 with mixed widths. +T}:T{ +Extra long text 123456789012 with mixed widths. +T} +.TE +.sp + +.TS +allbox tab(:); +lt. +T{ +Link check +T} +T{ +\fIfoo\fR +T} +T{ + +T} +.TE +.sp diff --git a/crates/mdman/tests/compare/expected/tables.md b/crates/mdman/tests/compare/expected/tables.md new file mode 100644 index 00000000000..831132c44ec --- /dev/null +++ b/crates/mdman/tests/compare/expected/tables.md @@ -0,0 +1,35 @@ +# tables(1) + +## DESCRIPTION + +Testing tables. + +| Single col | +-------------- +| Hi! :) | + + +Header content | With `format` *text* | Another column +---------------|----------------------|---------------- +Some data | More data | +Extra long amount of text within a column | hi | there + + +Left aligned | Center aligned | Right aligned +-------------|:--------------:|--------------: +abc | def | ghi + + +Left aligned | Center aligned | Right aligned +-------------|:--------------:|--------------: +X | X | X +Extra long text 123456789012 with mixed widths. | Extra long text 123456789012 with mixed widths. | Extra long text 123456789012 with mixed widths. + + +| Link check | +-------------- +| [foo] | +| | + + +[foo]: https://example.com/ diff --git a/crates/mdman/tests/compare/expected/tables.txt b/crates/mdman/tests/compare/expected/tables.txt new file mode 100644 index 00000000000..fed53f9a487 --- /dev/null +++ b/crates/mdman/tests/compare/expected/tables.txt @@ -0,0 +1,45 @@ +TABLES(1) + +DESCRIPTION + Testing tables. + + +-------------+ + | Single col | + +-------------+ + | Hi! :) | + +-------------+ + + +-------------------------------------+----------------+--------------+ + | Header content | With format | Another | + | | text | column | + +-------------------------------------+----------------+--------------+ + | Some data | More data | | + +-------------------------------------+----------------+--------------+ + | Extra long amount of text within a | hi | there | + | column | | | + +-------------------------------------+----------------+--------------+ + + +---------------+-----------------+----------------+ + | Left aligned | Center aligned | Right aligned | + +---------------+-----------------+----------------+ + | abc | def | ghi | + +---------------+-----------------+----------------+ + + +-----------------------+-----------------------+-----------------------+ + | Left aligned | Center aligned | Right aligned | + +-----------------------+-----------------------+-----------------------+ + | X | X | X | + +-----------------------+-----------------------+-----------------------+ + | Extra long text | Extra long text | Extra long text | + | 123456789012 with | 123456789012 with | 123456789012 with | + | mixed widths. | mixed widths. | mixed widths. | + +-----------------------+-----------------------+-----------------------+ + + +-----------------------+ + | Link check | + +-----------------------+ + | foo | + +-----------------------+ + | https://example.com/ | + +-----------------------+ + diff --git a/crates/mdman/tests/compare/expected/vars.7 b/crates/mdman/tests/compare/expected/vars.7 new file mode 100644 index 00000000000..0ee33ad3657 --- /dev/null +++ b/crates/mdman/tests/compare/expected/vars.7 @@ -0,0 +1,9 @@ +'\" t +.TH "VARS" "7" +.nh +.ad l +.ss \n[.ss] 0 +.sp +Bar +.sp +bar diff --git a/crates/mdman/tests/compare/expected/vars.md b/crates/mdman/tests/compare/expected/vars.md new file mode 100644 index 00000000000..2493aca36f5 --- /dev/null +++ b/crates/mdman/tests/compare/expected/vars.md @@ -0,0 +1,7 @@ +# vars(7) + + + +Bar + +bar diff --git a/crates/mdman/tests/compare/expected/vars.txt b/crates/mdman/tests/compare/expected/vars.txt new file mode 100644 index 00000000000..11d34ca1228 --- /dev/null +++ b/crates/mdman/tests/compare/expected/vars.txt @@ -0,0 +1,6 @@ +VARS(7) + +Bar + +bar + diff --git a/crates/mdman/tests/compare/formatting.md b/crates/mdman/tests/compare/formatting.md new file mode 100644 index 00000000000..6909bd44343 --- /dev/null +++ b/crates/mdman/tests/compare/formatting.md @@ -0,0 +1,94 @@ +# formatting(1) + +This is **nested _formatting_ `text`**. + +## SECOND HEADING + +Some text at second level. + +### Third heading + +Some text at third level. + +#### Fourth heading + +Some text at fourth level. + +## Quotes and blocks. + +Here are some quotes and blocks. + +> This is a block quote. Ambidextrously koala apart that prudent blindly alas +> far amid dear goodness turgid so exact inside oh and alas much fanciful that +> dark on spoon-fed adequately insolent walking crud. + +``` +This is a code block. Groundhog watchfully sudden firefly some self-consciously hotly jeepers satanic after that this parrot this at virtuous +some mocking the leaned jeez nightingale as much mallard so because jeez +turned dear crud grizzly strenuously. + + Indented and should be unmodified. +``` + + This is an indented code block. Egregiously yikes animatedly since outside beseechingly a badger hey shakily giraffe a one wow one this + goodness regarding reindeer so astride before. + + Doubly indented + +## Lists + +1. Ordered list + + * Unordered list + + With a second paragraph inside it + + 1. Inner ordered list + + 1. Another + + * Eggs + + * Milk + 5. Don't start at one. + 6. tamarind + +1. Second element + +1. Third element + +## Breaks + +This has a\ +hard break in it +and a soft one. + +## Horizontal rule + +This should contain a line: + +--- + +Nice! + +## Strange characters + +Handles escaping for characters + +.dot at the start of a line. + +\fBnot really troff + +Various characters \ - – — ─ │ ├ └ + +``` +tree +└── example + ├── salamander + │ ├── honey + │ └── some + ├── fancifully + └── trout +``` + +    non-breaking space. diff --git a/crates/mdman/tests/compare/includes/options-common.md b/crates/mdman/tests/compare/includes/options-common.md new file mode 100644 index 00000000000..07404e3f74c --- /dev/null +++ b/crates/mdman/tests/compare/includes/options-common.md @@ -0,0 +1,14 @@ +{{#options}} +{{#option "`@`_filename_"}} +Load from filename. +{{/option}} + +{{#option "`--foo` [_bar_]"}} +Flag with optional value. +{{/option}} + +{{#option "`--foo`[`=`_bar_]"}} +Alternate syntax for optional value (with required = for disambiguation). +{{/option}} + +{{/options}} diff --git a/crates/mdman/tests/compare/links.md b/crates/mdman/tests/compare/links.md new file mode 100644 index 00000000000..d0ef2204021 --- /dev/null +++ b/crates/mdman/tests/compare/links.md @@ -0,0 +1,35 @@ +# links(1) + +## NAME + +links - Test of different link kinds + +## DESCRIPTION + +Inline link: [inline link](https://example.com/inline) + +Reference link: [this is a link][bar] + +Collapsed: [collapsed][] + +Shortcut: [shortcut] + +Autolink: + +Email: + +Relative link: [relative link](foo/bar.html) + +Collapsed unknown: [collapsed unknown][] + +Reference unknown: [foo][unknown] + +Shortcut unknown: [shortcut unknown] + +{{man "other-cmd" 1}} + +{{man "local-cmd" 1}} + +[bar]: https://example.com/bar +[collapsed]: https://example.com/collapsed +[shortcut]: https://example.com/shortcut diff --git a/crates/mdman/tests/compare/options.md b/crates/mdman/tests/compare/options.md new file mode 100644 index 00000000000..51415b09e56 --- /dev/null +++ b/crates/mdman/tests/compare/options.md @@ -0,0 +1,62 @@ +# my-command(1) + +## NAME + +my-command - A brief description + +## SYNOPSIS + +`my-command` [`--abc` | `--xyz`] _name_\ +`my-command` [`-f` _file_]\ +`my-command` (`-m` | `-M`) [_oldbranch_] _newbranch_\ +`my-command` (`-d` | `-D`) [`-r`] _branchname_... + +## DESCRIPTION + +A description of the command. + +* One + * Sub one + * Sub two +* Two +* Three + + +## OPTIONS + +### Command options + +{{#options}} + +{{#option "`--foo-bar`"}} +Demo *emphasis*, **strong**, ~~strike~~ +{{/option}} + +{{#option "`-p` _spec_" "`--package` _spec_"}} +This has multiple flags. +{{/option}} + +{{#option "_named-arg..._"}} +A named argument. +{{/option}} + +{{/options}} + +### Common Options + +{{> options-common}} + +## EXAMPLES + +1. An example + + ``` + my-command --abc + ``` + +1. Another example + + my-command --xyz + +## SEE ALSO +{{man "other-command" 1}} {{man "abc" 7}} diff --git a/crates/mdman/tests/compare/tables.md b/crates/mdman/tests/compare/tables.md new file mode 100644 index 00000000000..831132c44ec --- /dev/null +++ b/crates/mdman/tests/compare/tables.md @@ -0,0 +1,35 @@ +# tables(1) + +## DESCRIPTION + +Testing tables. + +| Single col | +-------------- +| Hi! :) | + + +Header content | With `format` *text* | Another column +---------------|----------------------|---------------- +Some data | More data | +Extra long amount of text within a column | hi | there + + +Left aligned | Center aligned | Right aligned +-------------|:--------------:|--------------: +abc | def | ghi + + +Left aligned | Center aligned | Right aligned +-------------|:--------------:|--------------: +X | X | X +Extra long text 123456789012 with mixed widths. | Extra long text 123456789012 with mixed widths. | Extra long text 123456789012 with mixed widths. + + +| Link check | +-------------- +| [foo] | +| | + + +[foo]: https://example.com/ diff --git a/crates/mdman/tests/compare/vars.md b/crates/mdman/tests/compare/vars.md new file mode 100644 index 00000000000..d41b7658395 --- /dev/null +++ b/crates/mdman/tests/compare/vars.md @@ -0,0 +1,7 @@ +# vars(7) + +{{*set foo="Bar"}} + +{{foo}} + +{{lower foo}} diff --git a/crates/mdman/tests/invalid.rs b/crates/mdman/tests/invalid.rs new file mode 100644 index 00000000000..cc81d06c427 --- /dev/null +++ b/crates/mdman/tests/invalid.rs @@ -0,0 +1,34 @@ +//! Tests for errors and invalid input. + +use mdman::{Format, ManMap}; +use pretty_assertions::assert_eq; +use std::path::PathBuf; + +fn run(name: &str, expected_error: &str) { + let input = PathBuf::from(format!("tests/invalid/{}", name)); + match mdman::convert(&input, Format::Man, None, ManMap::new()) { + Ok(_) => { + panic!("expected {} to fail", name); + } + Err(e) => { + assert_eq!(expected_error, e.to_string()); + } + } +} + +macro_rules! test( ($name:ident, $file_name:expr, $error:expr) => ( + #[test] + fn $name() { run($file_name, $error); } +) ); + +test!( + nested, + "nested.md", + "Error rendering \"template\" line 4, col 1: options blocks cannot be nested" +); + +test!( + not_inside_options, + "not-inside-options.md", + "Error rendering \"template\" line 3, col 1: option must be in options block" +); diff --git a/crates/mdman/tests/invalid/nested.md b/crates/mdman/tests/invalid/nested.md new file mode 100644 index 00000000000..6a33e6df6b4 --- /dev/null +++ b/crates/mdman/tests/invalid/nested.md @@ -0,0 +1,6 @@ +# nested(1) + +{{#options}} +{{#options}} +{{/options}} +{{/options}} diff --git a/crates/mdman/tests/invalid/not-inside-options.md b/crates/mdman/tests/invalid/not-inside-options.md new file mode 100644 index 00000000000..b6c816f09dd --- /dev/null +++ b/crates/mdman/tests/invalid/not-inside-options.md @@ -0,0 +1,5 @@ +# not-inside-options(1) + +{{#option "`-o`"}} +Testing without options block. +{{/option}} From 5594bfa4bde59eaedfdff6c1e77ee215f978e0e2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 1 Aug 2020 09:33:06 -0700 Subject: [PATCH 2/7] Move asciidoc man pages to markdown. --- src/doc/man/{cargo-bench.adoc => cargo-bench.md} | 0 src/doc/man/{cargo-build.adoc => cargo-build.md} | 0 src/doc/man/{cargo-check.adoc => cargo-check.md} | 0 src/doc/man/{cargo-clean.adoc => cargo-clean.md} | 0 src/doc/man/{cargo-doc.adoc => cargo-doc.md} | 0 src/doc/man/{cargo-fetch.adoc => cargo-fetch.md} | 0 src/doc/man/{cargo-fix.adoc => cargo-fix.md} | 0 .../{cargo-generate-lockfile.adoc => cargo-generate-lockfile.md} | 0 src/doc/man/{cargo-help.adoc => cargo-help.md} | 0 src/doc/man/{cargo-init.adoc => cargo-init.md} | 0 src/doc/man/{cargo-install.adoc => cargo-install.md} | 0 .../man/{cargo-locate-project.adoc => cargo-locate-project.md} | 0 src/doc/man/{cargo-login.adoc => cargo-login.md} | 0 src/doc/man/{cargo-metadata.adoc => cargo-metadata.md} | 0 src/doc/man/{cargo-new.adoc => cargo-new.md} | 0 src/doc/man/{cargo-owner.adoc => cargo-owner.md} | 0 src/doc/man/{cargo-package.adoc => cargo-package.md} | 0 src/doc/man/{cargo-pkgid.adoc => cargo-pkgid.md} | 0 src/doc/man/{cargo-publish.adoc => cargo-publish.md} | 0 src/doc/man/{cargo-run.adoc => cargo-run.md} | 0 src/doc/man/{cargo-rustc.adoc => cargo-rustc.md} | 0 src/doc/man/{cargo-rustdoc.adoc => cargo-rustdoc.md} | 0 src/doc/man/{cargo-search.adoc => cargo-search.md} | 0 src/doc/man/{cargo-test.adoc => cargo-test.md} | 0 src/doc/man/{cargo-tree.adoc => cargo-tree.md} | 0 src/doc/man/{cargo-uninstall.adoc => cargo-uninstall.md} | 0 src/doc/man/{cargo-update.adoc => cargo-update.md} | 0 src/doc/man/{cargo-vendor.adoc => cargo-vendor.md} | 0 .../man/{cargo-verify-project.adoc => cargo-verify-project.md} | 0 src/doc/man/{cargo-version.adoc => cargo-version.md} | 0 src/doc/man/{cargo-yank.adoc => cargo-yank.md} | 0 src/doc/man/{cargo.adoc => cargo.md} | 0 .../description-install-root.md} | 0 .../description-new-authors.md} | 0 .../description-one-target.md} | 0 src/doc/man/{options-display.adoc => includes/options-display.md} | 0 src/doc/man/{options-index.adoc => includes/options-index.md} | 0 src/doc/man/{options-jobs.adoc => includes/options-jobs.md} | 0 src/doc/man/{options-locked.adoc => includes/options-locked.md} | 0 .../options-manifest-path.md} | 0 .../options-message-format.md} | 0 src/doc/man/{options-new.adoc => includes/options-new.md} | 0 src/doc/man/{options-profile.adoc => includes/options-profile.md} | 0 .../man/{options-registry.adoc => includes/options-registry.md} | 0 src/doc/man/{options-release.adoc => includes/options-release.md} | 0 .../{options-target-dir.adoc => includes/options-target-dir.md} | 0 .../options-target-triple.md} | 0 .../options-targets-lib-bin.md} | 0 src/doc/man/{options-targets.adoc => includes/options-targets.md} | 0 src/doc/man/{options-test.adoc => includes/options-test.md} | 0 src/doc/man/{options-token.adoc => includes/options-token.md} | 0 .../{section-environment.adoc => includes/section-environment.md} | 0 .../{section-exit-status.adoc => includes/section-exit-status.md} | 0 .../man/{options-features.adoc => includes/section-features.md} | 0 .../{options-common.adoc => includes/section-options-common.md} | 0 .../{options-package.adoc => includes/section-options-package.md} | 0 .../section-package-selection.md} | 0 .../man/{section-profiles.adoc => includes/section-profiles.md} | 0 58 files changed, 0 insertions(+), 0 deletions(-) rename src/doc/man/{cargo-bench.adoc => cargo-bench.md} (100%) rename src/doc/man/{cargo-build.adoc => cargo-build.md} (100%) rename src/doc/man/{cargo-check.adoc => cargo-check.md} (100%) rename src/doc/man/{cargo-clean.adoc => cargo-clean.md} (100%) rename src/doc/man/{cargo-doc.adoc => cargo-doc.md} (100%) rename src/doc/man/{cargo-fetch.adoc => cargo-fetch.md} (100%) rename src/doc/man/{cargo-fix.adoc => cargo-fix.md} (100%) rename src/doc/man/{cargo-generate-lockfile.adoc => cargo-generate-lockfile.md} (100%) rename src/doc/man/{cargo-help.adoc => cargo-help.md} (100%) rename src/doc/man/{cargo-init.adoc => cargo-init.md} (100%) rename src/doc/man/{cargo-install.adoc => cargo-install.md} (100%) rename src/doc/man/{cargo-locate-project.adoc => cargo-locate-project.md} (100%) rename src/doc/man/{cargo-login.adoc => cargo-login.md} (100%) rename src/doc/man/{cargo-metadata.adoc => cargo-metadata.md} (100%) rename src/doc/man/{cargo-new.adoc => cargo-new.md} (100%) rename src/doc/man/{cargo-owner.adoc => cargo-owner.md} (100%) rename src/doc/man/{cargo-package.adoc => cargo-package.md} (100%) rename src/doc/man/{cargo-pkgid.adoc => cargo-pkgid.md} (100%) rename src/doc/man/{cargo-publish.adoc => cargo-publish.md} (100%) rename src/doc/man/{cargo-run.adoc => cargo-run.md} (100%) rename src/doc/man/{cargo-rustc.adoc => cargo-rustc.md} (100%) rename src/doc/man/{cargo-rustdoc.adoc => cargo-rustdoc.md} (100%) rename src/doc/man/{cargo-search.adoc => cargo-search.md} (100%) rename src/doc/man/{cargo-test.adoc => cargo-test.md} (100%) rename src/doc/man/{cargo-tree.adoc => cargo-tree.md} (100%) rename src/doc/man/{cargo-uninstall.adoc => cargo-uninstall.md} (100%) rename src/doc/man/{cargo-update.adoc => cargo-update.md} (100%) rename src/doc/man/{cargo-vendor.adoc => cargo-vendor.md} (100%) rename src/doc/man/{cargo-verify-project.adoc => cargo-verify-project.md} (100%) rename src/doc/man/{cargo-version.adoc => cargo-version.md} (100%) rename src/doc/man/{cargo-yank.adoc => cargo-yank.md} (100%) rename src/doc/man/{cargo.adoc => cargo.md} (100%) rename src/doc/man/{description-install-root.adoc => includes/description-install-root.md} (100%) rename src/doc/man/{description-new-authors.adoc => includes/description-new-authors.md} (100%) rename src/doc/man/{description-one-target.adoc => includes/description-one-target.md} (100%) rename src/doc/man/{options-display.adoc => includes/options-display.md} (100%) rename src/doc/man/{options-index.adoc => includes/options-index.md} (100%) rename src/doc/man/{options-jobs.adoc => includes/options-jobs.md} (100%) rename src/doc/man/{options-locked.adoc => includes/options-locked.md} (100%) rename src/doc/man/{options-manifest-path.adoc => includes/options-manifest-path.md} (100%) rename src/doc/man/{options-message-format.adoc => includes/options-message-format.md} (100%) rename src/doc/man/{options-new.adoc => includes/options-new.md} (100%) rename src/doc/man/{options-profile.adoc => includes/options-profile.md} (100%) rename src/doc/man/{options-registry.adoc => includes/options-registry.md} (100%) rename src/doc/man/{options-release.adoc => includes/options-release.md} (100%) rename src/doc/man/{options-target-dir.adoc => includes/options-target-dir.md} (100%) rename src/doc/man/{options-target-triple.adoc => includes/options-target-triple.md} (100%) rename src/doc/man/{options-targets-lib-bin.adoc => includes/options-targets-lib-bin.md} (100%) rename src/doc/man/{options-targets.adoc => includes/options-targets.md} (100%) rename src/doc/man/{options-test.adoc => includes/options-test.md} (100%) rename src/doc/man/{options-token.adoc => includes/options-token.md} (100%) rename src/doc/man/{section-environment.adoc => includes/section-environment.md} (100%) rename src/doc/man/{section-exit-status.adoc => includes/section-exit-status.md} (100%) rename src/doc/man/{options-features.adoc => includes/section-features.md} (100%) rename src/doc/man/{options-common.adoc => includes/section-options-common.md} (100%) rename src/doc/man/{options-package.adoc => includes/section-options-package.md} (100%) rename src/doc/man/{options-packages.adoc => includes/section-package-selection.md} (100%) rename src/doc/man/{section-profiles.adoc => includes/section-profiles.md} (100%) diff --git a/src/doc/man/cargo-bench.adoc b/src/doc/man/cargo-bench.md similarity index 100% rename from src/doc/man/cargo-bench.adoc rename to src/doc/man/cargo-bench.md diff --git a/src/doc/man/cargo-build.adoc b/src/doc/man/cargo-build.md similarity index 100% rename from src/doc/man/cargo-build.adoc rename to src/doc/man/cargo-build.md diff --git a/src/doc/man/cargo-check.adoc b/src/doc/man/cargo-check.md similarity index 100% rename from src/doc/man/cargo-check.adoc rename to src/doc/man/cargo-check.md diff --git a/src/doc/man/cargo-clean.adoc b/src/doc/man/cargo-clean.md similarity index 100% rename from src/doc/man/cargo-clean.adoc rename to src/doc/man/cargo-clean.md diff --git a/src/doc/man/cargo-doc.adoc b/src/doc/man/cargo-doc.md similarity index 100% rename from src/doc/man/cargo-doc.adoc rename to src/doc/man/cargo-doc.md diff --git a/src/doc/man/cargo-fetch.adoc b/src/doc/man/cargo-fetch.md similarity index 100% rename from src/doc/man/cargo-fetch.adoc rename to src/doc/man/cargo-fetch.md diff --git a/src/doc/man/cargo-fix.adoc b/src/doc/man/cargo-fix.md similarity index 100% rename from src/doc/man/cargo-fix.adoc rename to src/doc/man/cargo-fix.md diff --git a/src/doc/man/cargo-generate-lockfile.adoc b/src/doc/man/cargo-generate-lockfile.md similarity index 100% rename from src/doc/man/cargo-generate-lockfile.adoc rename to src/doc/man/cargo-generate-lockfile.md diff --git a/src/doc/man/cargo-help.adoc b/src/doc/man/cargo-help.md similarity index 100% rename from src/doc/man/cargo-help.adoc rename to src/doc/man/cargo-help.md diff --git a/src/doc/man/cargo-init.adoc b/src/doc/man/cargo-init.md similarity index 100% rename from src/doc/man/cargo-init.adoc rename to src/doc/man/cargo-init.md diff --git a/src/doc/man/cargo-install.adoc b/src/doc/man/cargo-install.md similarity index 100% rename from src/doc/man/cargo-install.adoc rename to src/doc/man/cargo-install.md diff --git a/src/doc/man/cargo-locate-project.adoc b/src/doc/man/cargo-locate-project.md similarity index 100% rename from src/doc/man/cargo-locate-project.adoc rename to src/doc/man/cargo-locate-project.md diff --git a/src/doc/man/cargo-login.adoc b/src/doc/man/cargo-login.md similarity index 100% rename from src/doc/man/cargo-login.adoc rename to src/doc/man/cargo-login.md diff --git a/src/doc/man/cargo-metadata.adoc b/src/doc/man/cargo-metadata.md similarity index 100% rename from src/doc/man/cargo-metadata.adoc rename to src/doc/man/cargo-metadata.md diff --git a/src/doc/man/cargo-new.adoc b/src/doc/man/cargo-new.md similarity index 100% rename from src/doc/man/cargo-new.adoc rename to src/doc/man/cargo-new.md diff --git a/src/doc/man/cargo-owner.adoc b/src/doc/man/cargo-owner.md similarity index 100% rename from src/doc/man/cargo-owner.adoc rename to src/doc/man/cargo-owner.md diff --git a/src/doc/man/cargo-package.adoc b/src/doc/man/cargo-package.md similarity index 100% rename from src/doc/man/cargo-package.adoc rename to src/doc/man/cargo-package.md diff --git a/src/doc/man/cargo-pkgid.adoc b/src/doc/man/cargo-pkgid.md similarity index 100% rename from src/doc/man/cargo-pkgid.adoc rename to src/doc/man/cargo-pkgid.md diff --git a/src/doc/man/cargo-publish.adoc b/src/doc/man/cargo-publish.md similarity index 100% rename from src/doc/man/cargo-publish.adoc rename to src/doc/man/cargo-publish.md diff --git a/src/doc/man/cargo-run.adoc b/src/doc/man/cargo-run.md similarity index 100% rename from src/doc/man/cargo-run.adoc rename to src/doc/man/cargo-run.md diff --git a/src/doc/man/cargo-rustc.adoc b/src/doc/man/cargo-rustc.md similarity index 100% rename from src/doc/man/cargo-rustc.adoc rename to src/doc/man/cargo-rustc.md diff --git a/src/doc/man/cargo-rustdoc.adoc b/src/doc/man/cargo-rustdoc.md similarity index 100% rename from src/doc/man/cargo-rustdoc.adoc rename to src/doc/man/cargo-rustdoc.md diff --git a/src/doc/man/cargo-search.adoc b/src/doc/man/cargo-search.md similarity index 100% rename from src/doc/man/cargo-search.adoc rename to src/doc/man/cargo-search.md diff --git a/src/doc/man/cargo-test.adoc b/src/doc/man/cargo-test.md similarity index 100% rename from src/doc/man/cargo-test.adoc rename to src/doc/man/cargo-test.md diff --git a/src/doc/man/cargo-tree.adoc b/src/doc/man/cargo-tree.md similarity index 100% rename from src/doc/man/cargo-tree.adoc rename to src/doc/man/cargo-tree.md diff --git a/src/doc/man/cargo-uninstall.adoc b/src/doc/man/cargo-uninstall.md similarity index 100% rename from src/doc/man/cargo-uninstall.adoc rename to src/doc/man/cargo-uninstall.md diff --git a/src/doc/man/cargo-update.adoc b/src/doc/man/cargo-update.md similarity index 100% rename from src/doc/man/cargo-update.adoc rename to src/doc/man/cargo-update.md diff --git a/src/doc/man/cargo-vendor.adoc b/src/doc/man/cargo-vendor.md similarity index 100% rename from src/doc/man/cargo-vendor.adoc rename to src/doc/man/cargo-vendor.md diff --git a/src/doc/man/cargo-verify-project.adoc b/src/doc/man/cargo-verify-project.md similarity index 100% rename from src/doc/man/cargo-verify-project.adoc rename to src/doc/man/cargo-verify-project.md diff --git a/src/doc/man/cargo-version.adoc b/src/doc/man/cargo-version.md similarity index 100% rename from src/doc/man/cargo-version.adoc rename to src/doc/man/cargo-version.md diff --git a/src/doc/man/cargo-yank.adoc b/src/doc/man/cargo-yank.md similarity index 100% rename from src/doc/man/cargo-yank.adoc rename to src/doc/man/cargo-yank.md diff --git a/src/doc/man/cargo.adoc b/src/doc/man/cargo.md similarity index 100% rename from src/doc/man/cargo.adoc rename to src/doc/man/cargo.md diff --git a/src/doc/man/description-install-root.adoc b/src/doc/man/includes/description-install-root.md similarity index 100% rename from src/doc/man/description-install-root.adoc rename to src/doc/man/includes/description-install-root.md diff --git a/src/doc/man/description-new-authors.adoc b/src/doc/man/includes/description-new-authors.md similarity index 100% rename from src/doc/man/description-new-authors.adoc rename to src/doc/man/includes/description-new-authors.md diff --git a/src/doc/man/description-one-target.adoc b/src/doc/man/includes/description-one-target.md similarity index 100% rename from src/doc/man/description-one-target.adoc rename to src/doc/man/includes/description-one-target.md diff --git a/src/doc/man/options-display.adoc b/src/doc/man/includes/options-display.md similarity index 100% rename from src/doc/man/options-display.adoc rename to src/doc/man/includes/options-display.md diff --git a/src/doc/man/options-index.adoc b/src/doc/man/includes/options-index.md similarity index 100% rename from src/doc/man/options-index.adoc rename to src/doc/man/includes/options-index.md diff --git a/src/doc/man/options-jobs.adoc b/src/doc/man/includes/options-jobs.md similarity index 100% rename from src/doc/man/options-jobs.adoc rename to src/doc/man/includes/options-jobs.md diff --git a/src/doc/man/options-locked.adoc b/src/doc/man/includes/options-locked.md similarity index 100% rename from src/doc/man/options-locked.adoc rename to src/doc/man/includes/options-locked.md diff --git a/src/doc/man/options-manifest-path.adoc b/src/doc/man/includes/options-manifest-path.md similarity index 100% rename from src/doc/man/options-manifest-path.adoc rename to src/doc/man/includes/options-manifest-path.md diff --git a/src/doc/man/options-message-format.adoc b/src/doc/man/includes/options-message-format.md similarity index 100% rename from src/doc/man/options-message-format.adoc rename to src/doc/man/includes/options-message-format.md diff --git a/src/doc/man/options-new.adoc b/src/doc/man/includes/options-new.md similarity index 100% rename from src/doc/man/options-new.adoc rename to src/doc/man/includes/options-new.md diff --git a/src/doc/man/options-profile.adoc b/src/doc/man/includes/options-profile.md similarity index 100% rename from src/doc/man/options-profile.adoc rename to src/doc/man/includes/options-profile.md diff --git a/src/doc/man/options-registry.adoc b/src/doc/man/includes/options-registry.md similarity index 100% rename from src/doc/man/options-registry.adoc rename to src/doc/man/includes/options-registry.md diff --git a/src/doc/man/options-release.adoc b/src/doc/man/includes/options-release.md similarity index 100% rename from src/doc/man/options-release.adoc rename to src/doc/man/includes/options-release.md diff --git a/src/doc/man/options-target-dir.adoc b/src/doc/man/includes/options-target-dir.md similarity index 100% rename from src/doc/man/options-target-dir.adoc rename to src/doc/man/includes/options-target-dir.md diff --git a/src/doc/man/options-target-triple.adoc b/src/doc/man/includes/options-target-triple.md similarity index 100% rename from src/doc/man/options-target-triple.adoc rename to src/doc/man/includes/options-target-triple.md diff --git a/src/doc/man/options-targets-lib-bin.adoc b/src/doc/man/includes/options-targets-lib-bin.md similarity index 100% rename from src/doc/man/options-targets-lib-bin.adoc rename to src/doc/man/includes/options-targets-lib-bin.md diff --git a/src/doc/man/options-targets.adoc b/src/doc/man/includes/options-targets.md similarity index 100% rename from src/doc/man/options-targets.adoc rename to src/doc/man/includes/options-targets.md diff --git a/src/doc/man/options-test.adoc b/src/doc/man/includes/options-test.md similarity index 100% rename from src/doc/man/options-test.adoc rename to src/doc/man/includes/options-test.md diff --git a/src/doc/man/options-token.adoc b/src/doc/man/includes/options-token.md similarity index 100% rename from src/doc/man/options-token.adoc rename to src/doc/man/includes/options-token.md diff --git a/src/doc/man/section-environment.adoc b/src/doc/man/includes/section-environment.md similarity index 100% rename from src/doc/man/section-environment.adoc rename to src/doc/man/includes/section-environment.md diff --git a/src/doc/man/section-exit-status.adoc b/src/doc/man/includes/section-exit-status.md similarity index 100% rename from src/doc/man/section-exit-status.adoc rename to src/doc/man/includes/section-exit-status.md diff --git a/src/doc/man/options-features.adoc b/src/doc/man/includes/section-features.md similarity index 100% rename from src/doc/man/options-features.adoc rename to src/doc/man/includes/section-features.md diff --git a/src/doc/man/options-common.adoc b/src/doc/man/includes/section-options-common.md similarity index 100% rename from src/doc/man/options-common.adoc rename to src/doc/man/includes/section-options-common.md diff --git a/src/doc/man/options-package.adoc b/src/doc/man/includes/section-options-package.md similarity index 100% rename from src/doc/man/options-package.adoc rename to src/doc/man/includes/section-options-package.md diff --git a/src/doc/man/options-packages.adoc b/src/doc/man/includes/section-package-selection.md similarity index 100% rename from src/doc/man/options-packages.adoc rename to src/doc/man/includes/section-package-selection.md diff --git a/src/doc/man/section-profiles.adoc b/src/doc/man/includes/section-profiles.md similarity index 100% rename from src/doc/man/section-profiles.adoc rename to src/doc/man/includes/section-profiles.md From 7b7d80e84ae74dd620c0f294d6f12ada16cdb94e Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 1 Aug 2020 09:35:24 -0700 Subject: [PATCH 3/7] Reformat asciidoc man pages to markdown. --- src/doc/man/cargo-bench.md | 115 +++---- src/doc/man/cargo-build.md | 111 +++---- src/doc/man/cargo-check.md | 88 +++--- src/doc/man/cargo-clean.md | 85 +++--- src/doc/man/cargo-doc.md | 108 ++++--- src/doc/man/cargo-fetch.md | 56 ++-- src/doc/man/cargo-fix.md | 140 +++++---- src/doc/man/cargo-generate-lockfile.md | 48 +-- src/doc/man/cargo-help.md | 26 +- src/doc/man/cargo-init.md | 46 ++- src/doc/man/cargo-install.md | 197 ++++++------ src/doc/man/cargo-locate-project.md | 46 +-- src/doc/man/cargo-login.md | 50 +-- src/doc/man/cargo-metadata.md | 84 ++--- src/doc/man/cargo-new.md | 46 ++- src/doc/man/cargo-owner.md | 83 ++--- src/doc/man/cargo-package.md | 107 ++++--- src/doc/man/cargo-pkgid.md | 99 +++--- src/doc/man/cargo-publish.md | 111 ++++--- src/doc/man/cargo-run.md | 102 ++++--- src/doc/man/cargo-rustc.md | 104 ++++--- src/doc/man/cargo-rustdoc.md | 106 ++++--- src/doc/man/cargo-search.md | 53 ++-- src/doc/man/cargo-test.md | 125 ++++---- src/doc/man/cargo-tree.md | 280 +++++++++-------- src/doc/man/cargo-uninstall.md | 66 ++-- src/doc/man/cargo-update.md | 95 +++--- src/doc/man/cargo-vendor.md | 97 +++--- src/doc/man/cargo-verify-project.md | 53 ++-- src/doc/man/cargo-version.md | 44 +-- src/doc/man/cargo-yank.md | 62 ++-- src/doc/man/cargo.md | 287 +++++++++--------- .../man/includes/description-install-root.md | 2 +- .../man/includes/description-new-authors.md | 2 +- src/doc/man/includes/options-display.md | 28 +- src/doc/man/includes/options-index.md | 5 +- src/doc/man/includes/options-jobs.md | 10 +- src/doc/man/includes/options-locked.md | 33 +- src/doc/man/includes/options-manifest-path.md | 7 +- .../man/includes/options-message-format.md | 11 +- src/doc/man/includes/options-new.md | 60 ++-- src/doc/man/includes/options-profile.md | 13 +- src/doc/man/includes/options-registry.md | 10 +- src/doc/man/includes/options-release.md | 8 +- src/doc/man/includes/options-target-dir.md | 11 +- src/doc/man/includes/options-target-triple.md | 19 +- .../man/includes/options-targets-lib-bin.md | 15 +- src/doc/man/includes/options-targets.md | 89 +++--- src/doc/man/includes/options-test.md | 20 +- src/doc/man/includes/options-token.md | 11 +- src/doc/man/includes/section-environment.md | 4 +- src/doc/man/includes/section-exit-status.md | 9 +- src/doc/man/includes/section-features.md | 28 +- .../man/includes/section-options-common.md | 35 ++- .../man/includes/section-options-package.md | 14 +- .../man/includes/section-package-selection.md | 35 ++- src/doc/man/includes/section-profiles.md | 24 +- 57 files changed, 1947 insertions(+), 1676 deletions(-) diff --git a/src/doc/man/cargo-bench.md b/src/doc/man/cargo-bench.md index 79acc6f2674..b47a1a079b4 100644 --- a/src/doc/man/cargo-bench.md +++ b/src/doc/man/cargo-bench.md @@ -1,27 +1,25 @@ -= cargo-bench(1) -:idprefix: cargo_bench_ -:doctype: manpage -:actionverb: Benchmark -:nouns: benchmarks +# cargo-bench(1) +{{*set actionverb="Benchmark"}} +{{*set nouns="benchmarks"}} -== NAME +## NAME cargo-bench - Execute benchmarks of a package -== SYNOPSIS +## SYNOPSIS -`cargo bench [_OPTIONS_] [BENCHNAME] [-- _BENCH-OPTIONS_]` +`cargo bench` [_options_] [_benchname_] [`--` _bench-options_] -== DESCRIPTION +## DESCRIPTION Compile and execute benchmarks. -The benchmark filtering argument `BENCHNAME` and all the arguments following +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 +_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after `--` go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of `cargo bench -- --help`. As an example, this will run only the benchmark named `foo` (and skip other similarly named benchmarks like `foobar`): @@ -36,27 +34,24 @@ The libtest harness may be disabled by setting `harness = false` in the target manifest settings, in which case your code will need to provide its own `main` function to handle running benchmarks. - > **Note**: The -> link:https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html[`#[bench\]` attribute] +> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html) > is currently unstable and only available on the -> link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel]. +> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html). > There are some packages available on -> link:https://crates.io/keywords/benchmark[crates.io] that may help with +> [crates.io](https://crates.io/keywords/benchmark) that may help with > running benchmarks on the stable channel, such as -> link:https://crates.io/crates/criterion[Criterion]. - -== OPTIONS +> [Criterion](https://crates.io/crates/criterion). -=== Benchmark Options +## OPTIONS -include::options-test.adoc[] +### Benchmark Options -=== Package Selection +{{> options-test }} -include::options-packages.adoc[] +{{> section-package-selection }} -=== Target Selection +### Target Selection When no target selection options are given, `cargo bench` will build the following targets of the selected packages: @@ -75,19 +70,25 @@ 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[] +{{> options-targets }} + +{{> section-features }} -include::options-features.adoc[] +### Compilation Options -=== Compilation Options +{{#options}} -include::options-target-triple.adoc[] +{{> options-target-triple }} -=== Output Options +{{/options}} -include::options-target-dir.adoc[] +### Output Options -=== Display Options +{{#options}} +{{> options-target-dir }} +{{/options}} + +### Display Options By default the Rust test harness hides output from benchmark execution to keep results readable. Benchmark output can be recovered (e.g., for debugging) by @@ -95,33 +96,39 @@ passing `--nocapture` to the benchmark binaries: cargo bench -- --nocapture -include::options-display.adoc[] +{{#options}} + +{{> options-display }} -include::options-message-format.adoc[] +{{> options-message-format }} -=== Manifest Options +{{/options}} -include::options-manifest-path.adoc[] +### Manifest Options -include::options-locked.adoc[] +{{#options}} +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -=== Miscellaneous Options +### 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[] +{{#options}} +{{> options-jobs }} +{{/options}} -== PROFILES +## PROFILES Profiles may be used to configure compiler options such as optimization levels and debug settings. See -linkcargo:reference/profiles.html[the reference] +[the reference](../reference/profiles.html) for more details. Benchmarks are always built with the `bench` profile. Binary and lib targets @@ -130,23 +137,23 @@ 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 +{{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[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Build and execute all the benchmarks of the current package: +1. Build and execute all the benchmarks of the current package: - cargo bench + cargo bench -. Run only a specific benchmark within a specific benchmark target: +2. Run only a specific benchmark within a specific benchmark target: - cargo bench --bench bench_name -- modname::some_benchmark + cargo bench --bench bench_name -- modname::some_benchmark -== SEE ALSO -man:cargo[1], man:cargo-test[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-test" 1}} diff --git a/src/doc/man/cargo-build.md b/src/doc/man/cargo-build.md index a7b20d7de64..fb24c5a000b 100644 --- a/src/doc/man/cargo-build.md +++ b/src/doc/man/cargo-build.md @@ -1,98 +1,107 @@ -= cargo-build(1) -:idprefix: cargo_build_ -:doctype: manpage -:actionverb: Build +# cargo-build(1) +{{*set actionverb="Build"}} -== NAME +## NAME cargo-build - Compile the current package -== SYNOPSIS +## SYNOPSIS -`cargo build [_OPTIONS_]` +`cargo build` [_options_] -== DESCRIPTION +## DESCRIPTION Compile local packages and all of their dependencies. -== OPTIONS +## OPTIONS -=== Package Selection +{{> section-package-selection }} -include::options-packages.adoc[] - -=== Target Selection +### Target Selection When no target selection options are given, `cargo build` will build all binary and library targets of the selected packages. Binaries are skipped if they have `required-features` that are missing. -include::options-targets.adoc[] +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} -include::options-features.adoc[] +{{> options-target-triple }} -=== Compilation Options +{{> options-release }} -include::options-target-triple.adoc[] +{{/options}} -include::options-release.adoc[] +### Output Options -=== Output Options +{{#options}} +{{> options-target-dir }} -include::options-target-dir.adoc[] +{{#option "`--out-dir` _directory_" }} +Copy final artifacts to this directory. -*--out-dir* _DIRECTORY_:: - Copy final artifacts to this directory. -+ This option is unstable and available only on the -link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel] +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) and requires the `-Z unstable-options` flag to enable. See https://github.com/rust-lang/cargo/issues/6790 for more information. +{{/option}} -=== Display Options +{{/options}} -include::options-display.adoc[] +### Display Options -include::options-message-format.adoc[] +{{#options}} +{{> options-display }} + +{{> options-message-format }} + +{{#option "`--build-plan`" }} +Outputs a series of JSON messages to stdout that indicate the commands to run +the build. -*--build-plan*:: - Outputs a series of JSON messages to stdout that indicate the commands to - run the build. -+ This option is unstable and available only on the -link:https://doc.rust-lang.org/book/appendix-07-nightly-rust.html[nightly channel] +[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) and requires the `-Z unstable-options` flag to enable. -See https://github.com/rust-lang/cargo/issues/5579 for more information. - -=== Manifest Options +See for more information. +{{/option}} +{{/options}} -include::options-manifest-path.adoc[] +### Manifest Options -include::options-locked.adoc[] +{{#options}} +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -=== Miscellaneous Options +### Miscellaneous Options -include::options-jobs.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-profiles.adoc[] +{{> section-profiles }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Build the local package and all of its dependencies: +1. Build the local package and all of its dependencies: - cargo build + cargo build -. Build with optimizations: +2. Build with optimizations: - cargo build --release + cargo build --release -== SEE ALSO -man:cargo[1], man:cargo-rustc[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-rustc" 1}} diff --git a/src/doc/man/cargo-check.md b/src/doc/man/cargo-check.md index c84b1dcef4c..b012e25020c 100644 --- a/src/doc/man/cargo-check.md +++ b/src/doc/man/cargo-check.md @@ -1,17 +1,15 @@ -= cargo-check(1) -:idprefix: cargo_check_ -:doctype: manpage -:actionverb: Check +# cargo-check(1) +{{*set actionverb="Check"}} -== NAME +## NAME cargo-check - Check the current package -== SYNOPSIS +## SYNOPSIS -`cargo check [_OPTIONS_]` +`cargo check` [_options_] -== DESCRIPTION +## 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 @@ -19,69 +17,77 @@ 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 +## OPTIONS -=== Package Selection +{{> section-package-selection }} -include::options-packages.adoc[] - -=== Target Selection +### Target Selection When no target selection options are given, `cargo check` will check all binary and library targets of the selected packages. Binaries are skipped if they have `required-features` that are missing. -include::options-targets.adoc[] +{{> options-targets }} + +{{> section-features }} -include::options-features.adoc[] +### Compilation Options -=== Compilation Options +{{#options}} -include::options-target-triple.adoc[] +{{> options-target-triple }} -include::options-release.adoc[] +{{> options-release }} -include::options-profile.adoc[] +{{> options-profile }} -=== Output Options +{{/options}} -include::options-target-dir.adoc[] +### Output Options -=== Display Options +{{#options}} +{{> options-target-dir }} +{{/options}} -include::options-display.adoc[] +### Display Options -include::options-message-format.adoc[] +{{#options}} +{{> options-display }} -=== Manifest Options +{{> options-message-format }} +{{/options}} -include::options-manifest-path.adoc[] +### Manifest Options -include::options-locked.adoc[] +{{#options}} +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -=== Miscellaneous Options +### Miscellaneous Options -include::options-jobs.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-profiles.adoc[] +{{> section-profiles }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Check the local package for errors: +1. Check the local package for errors: - cargo check + cargo check -. Check all targets, including unit tests: +2. Check all targets, including unit tests: - cargo check --all-targets --profile=test + cargo check --all-targets --profile=test -== SEE ALSO -man:cargo[1], man:cargo-build[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-clean.md b/src/doc/man/cargo-clean.md index 08fdb76deb3..d7d50840a9c 100644 --- a/src/doc/man/cargo-clean.md +++ b/src/doc/man/cargo-clean.md @@ -1,76 +1,83 @@ -= cargo-clean(1) -:idprefix: cargo_clean_ -:doctype: manpage -:actionverb: Clean +# cargo-clean(1) +{{*set actionverb="Clean"}} -== NAME +## NAME cargo-clean - Remove generated artifacts -== SYNOPSIS +## SYNOPSIS -`cargo clean [_OPTIONS_]` +`cargo clean` [_options_] -== DESCRIPTION +## 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 +## OPTIONS -=== Package Selection +### 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. +{{#options}} +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Clean only the specified packages. This flag may be specified +multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format. +{{/option}} +{{/options}} -=== Clean Options +### Clean Options -*--doc*:: - This option will cause `cargo clean` to remove only the `doc` directory in - the target directory. +{{#options}} -*--release*:: - Clean all artifacts that were built with the `release` or `bench` - profiles. +{{#option "`--doc`" }} +This option will cause `cargo clean` to remove only the `doc` directory in +the target directory. +{{/option}} -include::options-target-dir.adoc[] +{{#option "`--release`" }} +Clean all artifacts that were built with the `release` or `bench` profiles. +{{/option}} -include::options-target-triple.adoc[] +{{> options-target-dir }} -=== Display Options +{{> options-target-triple }} -include::options-display.adoc[] +{{/options}} -=== Manifest Options +### Display Options -include::options-manifest-path.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -include::options-locked.adoc[] +### Manifest Options -=== Common Options +{{#options}} +{{> options-manifest-path }} -include::options-common.adoc[] +{{> options-locked }} +{{/options}} -include::section-environment.adoc[] +{{> section-options-common }} -include::section-exit-status.adoc[] +{{> section-environment }} -== EXAMPLES +{{> section-exit-status }} -. Remove the entire target directory: +## EXAMPLES - cargo clean +1. Remove the entire target directory: -. Remove only the release artifacts: + cargo clean - cargo clean --release +2. Remove only the release artifacts: -== SEE ALSO -man:cargo[1], man:cargo-build[1] + cargo clean --release + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-doc.md b/src/doc/man/cargo-doc.md index 70e37dff913..20a9c2589d1 100644 --- a/src/doc/man/cargo-doc.md +++ b/src/doc/man/cargo-doc.md @@ -1,41 +1,43 @@ -= cargo-doc(1) -:idprefix: cargo_doc_ -:doctype: manpage -:actionverb: Document +# cargo-doc(1) +{{*set actionverb="Document"}} -== NAME +## NAME cargo-doc - Build a package's documentation -== SYNOPSIS +## SYNOPSIS -`cargo doc [_OPTIONS_]` +`cargo doc` [_options_] -== DESCRIPTION +## DESCRIPTION Build the documentation for the local package and all dependencies. The output is placed in `target/doc` in rustdoc's usual format. -== OPTIONS +## OPTIONS -=== Documentation Options +### Documentation Options -*--open*:: - Open the docs in a browser after building them. This will use your default - browser unless you define another one in the `BROWSER` environment - variable. +{{#options}} -*--no-deps*:: - Do not build documentation for dependencies. +{{#option "`--open`" }} +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the `BROWSER` environment variable. +{{/option}} -*--document-private-items*:: - Include non-public items in the documentation. +{{#option "`--no-deps`" }} +Do not build documentation for dependencies. +{{/option}} -=== Package Selection +{{#option "`--document-private-items`" }} +Include non-public items in the documentation. +{{/option}} -include::options-packages.adoc[] +{{/options}} -=== Target Selection +{{> section-package-selection }} + +### Target Selection When no target selection options are given, `cargo doc` will document all binary and library targets of the selected package. The binary will be skipped @@ -46,52 +48,64 @@ 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[] +{{#options}} +{{> options-targets-lib-bin }} +{{/options}} + +{{> section-features }} -include::options-features.adoc[] +### Compilation Options -=== Compilation Options +{{#options}} -include::options-target-triple.adoc[] +{{> options-target-triple }} -include::options-release.adoc[] +{{> options-release }} -=== Output Options +{{/options}} -include::options-target-dir.adoc[] +### Output Options -=== Display Options +{{#options}} +{{> options-target-dir }} +{{/options}} -include::options-display.adoc[] +### Display Options -include::options-message-format.adoc[] +{{#options}} +{{> options-display }} -=== Manifest Options +{{> options-message-format }} +{{/options}} -include::options-manifest-path.adoc[] +### Manifest Options -include::options-locked.adoc[] +{{#options}} +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -=== Miscellaneous Options +### Miscellaneous Options -include::options-jobs.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-profiles.adoc[] +{{> section-profiles }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Build the local package documentation and its dependencies and output to -`target/doc`. +1. Build the local package documentation and its dependencies and output to + `target/doc`. - cargo doc + cargo doc -== SEE ALSO -man:cargo[1], man:cargo-rustdoc[1], man:rustdoc[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-rustdoc" 1}}, {{man "rustdoc" 1}} diff --git a/src/doc/man/cargo-fetch.md b/src/doc/man/cargo-fetch.md index 3a12882b13e..2cca5f79748 100644 --- a/src/doc/man/cargo-fetch.md +++ b/src/doc/man/cargo-fetch.md @@ -1,17 +1,15 @@ -= cargo-fetch(1) -:idprefix: cargo_fetch_ -:doctype: manpage -:actionverb: Fetch +# cargo-fetch(1) +{{*set actionverb="Fetch"}} -== NAME +## NAME cargo-fetch - Fetch dependencies of a package from the network -== SYNOPSIS +## SYNOPSIS -`cargo fetch [_OPTIONS_]` +`cargo fetch` [_options_] -== DESCRIPTION +## 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 @@ -23,39 +21,43 @@ file before fetching the dependencies. If `--target` is not specified, then all target dependencies are fetched. -See also the link:https://crates.io/crates/cargo-prefetch[cargo-prefetch] +See also the [cargo-prefetch](https://crates.io/crates/cargo-prefetch) plugin which adds a command to download popular crates. This may be useful if you plan to use Cargo without a network with the `--offline` flag. -== OPTIONS +## OPTIONS -=== Fetch options +### Fetch options -include::options-target-triple.adoc[] +{{#options}} +{{> options-target-triple }} +{{/options}} -=== Display Options +### Display Options -include::options-display.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -=== Manifest Options +### Manifest Options -include::options-manifest-path.adoc[] +{{#options}} +{{> options-manifest-path }} -include::options-locked.adoc[] +{{> options-locked }} +{{/options}} -=== Common Options +{{> section-options-common }} -include::options-common.adoc[] +{{> section-environment }} -include::section-environment.adoc[] +{{> section-exit-status }} -include::section-exit-status.adoc[] +## EXAMPLES -== EXAMPLES +1. Fetch all dependencies: -. Fetch all dependencies: + cargo fetch - cargo fetch - -== SEE ALSO -man:cargo[1], man:cargo-update[1], man:cargo-generate-lockfile[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-update" 1}}, {{man "cargo-generate-lockfile" 1}} diff --git a/src/doc/man/cargo-fix.md b/src/doc/man/cargo-fix.md index 0cc8c3da4f8..606fe1acd62 100644 --- a/src/doc/man/cargo-fix.md +++ b/src/doc/man/cargo-fix.md @@ -1,17 +1,15 @@ -= cargo-fix(1) -:idprefix: cargo_fix_ -:doctype: manpage -:actionverb: Fix +# cargo-fix(1) +{{*set actionverb="Fix"}} -== NAME +## NAME cargo-fix - Automatically fix lint warnings reported by rustc -== SYNOPSIS +## SYNOPSIS -`cargo fix [_OPTIONS_]` +`cargo fix` [_options_] -== DESCRIPTION +## DESCRIPTION This Cargo subcommand will automatically take rustc's suggestions from diagnostics like warnings and apply them to your source code. This is intended @@ -20,7 +18,7 @@ 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 +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 @@ -43,100 +41,118 @@ pass `--target` to fix code for the given target. 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 +## OPTIONS -=== Fix 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. +{{#options}} -*--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. +{{#option "`--broken-code`" }} +Fix code even if it already has compiler errors. This is useful if `cargo fix` +fails to apply the changes. It will apply the changes and leave the broken +code in the working directory for you to inspect and manually fix. +{{/option}} -*--edition-idioms*:: - Apply suggestions that will update code to the preferred style for the - current edition. +{{#option "`--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. +{{/option}} -*--allow-no-vcs*:: - Fix code even if a VCS was not detected. +{{#option "`--edition-idioms`" }} +Apply suggestions that will update code to the preferred style for the current +edition. +{{/option}} -*--allow-dirty*:: - Fix code even if the working directory has changes. +{{#option "`--allow-no-vcs`" }} +Fix code even if a VCS was not detected. +{{/option}} -*--allow-staged*:: - Fix code even if the working directory has staged changes. +{{#option "`--allow-dirty`" }} +Fix code even if the working directory has changes. +{{/option}} -=== Package Selection +{{#option "`--allow-staged`" }} +Fix code even if the working directory has staged changes. +{{/option}} -include::options-packages.adoc[] +{{/options}} -=== Target Selection +{{> section-package-selection }} + +### Target Selection When no target selection options are given, `cargo fix` will fix all targets (`--all-targets` implied). Binaries are skipped if they have `required-features` that are missing. -include::options-targets.adoc[] +{{> options-targets }} -include::options-features.adoc[] +{{> section-features }} -=== Compilation Options +### Compilation Options -include::options-target-triple.adoc[] +{{#options}} -include::options-release.adoc[] +{{> options-target-triple }} -include::options-profile.adoc[] +{{> options-release }} -=== Output Options +{{> options-profile }} -include::options-target-dir.adoc[] +{{/options}} -=== Display Options +### Output Options -include::options-display.adoc[] +{{#options}} +{{> options-target-dir }} +{{/options}} -include::options-message-format.adoc[] +### Display Options -=== Manifest Options +{{#options}} +{{> options-display }} -include::options-manifest-path.adoc[] +{{> options-message-format }} +{{/options}} -include::options-locked.adoc[] +### Manifest Options -=== Common Options +{{#options}} +{{> options-manifest-path }} -include::options-common.adoc[] +{{> options-locked }} +{{/options}} -=== Miscellaneous Options +{{> section-options-common }} -include::options-jobs.adoc[] +### Miscellaneous Options -include::section-profiles.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-environment.adoc[] +{{> section-profiles }} -include::section-exit-status.adoc[] +{{> section-environment }} -== EXAMPLES +{{> section-exit-status }} -. Apply compiler suggestions to the local package: +## EXAMPLES - cargo fix +1. Apply compiler suggestions to the local package: -. Convert a 2015 edition to 2018: + cargo fix - cargo fix --edition +2. Convert a 2015 edition to 2018: + + cargo fix --edition -. Apply suggested idioms for the current edition: +3. Apply suggested idioms for the current edition: - cargo fix --edition-idioms + cargo fix --edition-idioms -== SEE ALSO -man:cargo[1], man:cargo-check[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-check" 1}} diff --git a/src/doc/man/cargo-generate-lockfile.md b/src/doc/man/cargo-generate-lockfile.md index 2b89159782d..2bc1828e488 100644 --- a/src/doc/man/cargo-generate-lockfile.md +++ b/src/doc/man/cargo-generate-lockfile.md @@ -1,49 +1,49 @@ -= cargo-generate-lockfile(1) -:idprefix: cargo_generate-lockfile_ -:doctype: manpage +# cargo-generate-lockfile(1) -== NAME +## NAME cargo-generate-lockfile - Generate the lockfile for a package -== SYNOPSIS +## SYNOPSIS -`cargo generate-lockfile [_OPTIONS_]` +`cargo generate-lockfile` [_options_] -== DESCRIPTION +## 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` +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 +## OPTIONS -=== Display Options +### Display Options -include::options-display.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -=== Manifest Options +### Manifest Options -include::options-manifest-path.adoc[] +{{#options}} +{{> options-manifest-path }} -include::options-locked.adoc[] +{{> options-locked }} +{{/options}} -=== Common Options +{{> section-options-common }} -include::options-common.adoc[] +{{> section-environment }} -include::section-environment.adoc[] +{{> section-exit-status }} -include::section-exit-status.adoc[] +## EXAMPLES -== EXAMPLES +1. Create or update the lockfile for the current package or workspace: -. Create or update the lockfile for the current package or workspace: + cargo generate-lockfile - cargo generate-lockfile - -== SEE ALSO -man:cargo[1], man:cargo-update[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-update" 1}} diff --git a/src/doc/man/cargo-help.md b/src/doc/man/cargo-help.md index bcbb5ba34c3..edd8bc0cb1a 100644 --- a/src/doc/man/cargo-help.md +++ b/src/doc/man/cargo-help.md @@ -1,28 +1,26 @@ -= cargo-help(1) -:idprefix: cargo_help_ -:doctype: manpage +# cargo-help(1) -== NAME +## NAME cargo-help - Get help for a Cargo command -== SYNOPSIS +## SYNOPSIS -`cargo help [_SUBCOMMAND_]` +`cargo help` [_subcommand_] -== DESCRIPTION +## DESCRIPTION Prints a help message for the given command. -== EXAMPLES +## EXAMPLES -. Get help for a command: +1. Get help for a command: - cargo help build + cargo help build -. Help is also available with the `--help` flag: +2. Help is also available with the `--help` flag: - cargo build --help + cargo build --help -== SEE ALSO -man:cargo[1] +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-init.md b/src/doc/man/cargo-init.md index 6df38bf6836..74e916fab82 100644 --- a/src/doc/man/cargo-init.md +++ b/src/doc/man/cargo-init.md @@ -1,16 +1,14 @@ -= cargo-init(1) -:idprefix: cargo_init_ -:doctype: manpage +# cargo-init(1) -== NAME +## NAME cargo-init - Create a new Cargo package in an existing directory -== SYNOPSIS +## SYNOPSIS -`cargo init [_OPTIONS_] [_PATH_]` +`cargo init` [_options_] [_path_] -== DESCRIPTION +## 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. @@ -22,34 +20,34 @@ will be used. If not, then a sample `src/main.rs` file will be created, or If the directory is not already in a VCS repository, then a new repository is created (see `--vcs` below). -include::description-new-authors.adoc[] +{{> description-new-authors }} -See man:cargo-new[1] for a similar command which will create a new package in +See {{man "cargo-new" 1}} for a similar command which will create a new package in a new directory. -== OPTIONS +## OPTIONS -=== Init Options +### Init Options -include::options-new.adoc[] +{{> options-new }} -=== Display Options +### Display Options -include::options-display.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -=== Common Options +{{> section-options-common }} -include::options-common.adoc[] +{{> section-environment }} -include::section-environment.adoc[] +{{> section-exit-status }} -include::section-exit-status.adoc[] +## EXAMPLES -== EXAMPLES +1. Create a binary Cargo package in the current directory: -. Create a binary Cargo package in the current directory: + cargo init - cargo init - -== SEE ALSO -man:cargo[1], man:cargo-new[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-new" 1}} diff --git a/src/doc/man/cargo-install.md b/src/doc/man/cargo-install.md index 6c96fdcf91f..3e1bc02fe94 100644 --- a/src/doc/man/cargo-install.md +++ b/src/doc/man/cargo-install.md @@ -1,33 +1,30 @@ -= cargo-install(1) -:idprefix: cargo_install_ -:doctype: manpage -:actionverb: Install +# cargo-install(1) +{{*set actionverb="Install"}} -== NAME +## NAME cargo-install - Build and install a Rust binary -== SYNOPSIS +## SYNOPSIS -[%hardbreaks] -`cargo install [_OPTIONS_] _CRATE_...` -`cargo install [_OPTIONS_] --path _PATH_` -`cargo install [_OPTIONS_] --git _URL_ [_CRATE_...]` -`cargo install [_OPTIONS_] --list` +`cargo install` [_options_] _crate_...\ +`cargo install` [_options_] `--path` _path_\ +`cargo install` [_options_] `--git` _url_ [_crate_...]\ +`cargo install` [_options_] `--list` -== DESCRIPTION +## DESCRIPTION This command manages Cargo's local set of installed binary crates. Only -packages which have executable `\[[bin]]` or `\[[example]]` targets can be +packages which have executable `[[bin]]` or `[[example]]` targets can be installed, and all executables are installed into the installation root's `bin` folder. -include::description-install-root.adoc[] +{{> description-install-root }} There are multiple sources from which a crate can be installed. The default location is crates.io but the `--git`, `--path`, and `--registry` flags can change this source. If the source contains more than one package (such as -crates.io or a git repository with multiple crates) the _CRATE_ argument is +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 @@ -71,116 +68,140 @@ not start publishing `Cargo.lock` files until version 1.37, which means packages published with prior versions will not have a `Cargo.lock` file available. -== OPTIONS +## OPTIONS -=== Install Options +### Install Options -*--vers* _VERSION_:: -*--version* _VERSION_:: - Specify a version to install. This may be a - linkcargo:reference/specifying-dependencies.md[version requirement], like - `~1.2`, to have Cargo select the newest version from the given - requirement. If the version does not have a requirement operator (such as - `^` or `~`), then it must be in the form _MAJOR.MINOR.PATCH_, and will - install exactly that version; it is *not* treated as a caret requirement - like Cargo dependencies are. +{{#options}} -*--git* _URL_:: - Git URL to install the specified crate from. +{{#option "`--vers` _version_" "`--version` _version_" }} +Specify a version to install. This may be a [version +requirement](../reference/specifying-dependencies.md), like `~1.2`, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as `^` or `~`), then it must be in the form +_MAJOR.MINOR.PATCH_, and will install exactly that version; it is *not* +treated as a caret requirement like Cargo dependencies are. +{{/option}} -*--branch* _BRANCH_:: - Branch to use when installing from git. +{{#option "`--git` _url_" }} +Git URL to install the specified crate from. +{{/option}} -*--tag* _TAG_:: - Tag to use when installing from git. +{{#option "`--branch` _branch_" }} +Branch to use when installing from git. +{{/option}} -*--rev* _SHA_:: - Specific commit to use when installing from git. +{{#option "`--tag` _tag_" }} +Tag to use when installing from git. +{{/option}} -*--path* _PATH_:: - Filesystem path to local crate to install. +{{#option "`--rev` _sha_" }} +Specific commit to use when installing from git. +{{/option}} -*--list*:: - List all installed packages and their versions. +{{#option "`--path` _path_" }} +Filesystem path to local crate to install. +{{/option}} -*-f*:: -*--force*:: - Force overwriting existing crates or binaries. This can be used if a - package has installed a binary with the same name as another package. This - is also useful if something has changed on the system that you want to - rebuild with, such as a newer version of `rustc`. +{{#option "`--list`" }} +List all installed packages and their versions. +{{/option}} -*--no-track*:: - By default, Cargo keeps track of the installed packages with a metadata - file stored in the installation root directory. This flag tells Cargo not - to use or create that file. With this flag, Cargo will refuse to overwrite - any existing files unless the `--force` flag is used. This also disables - Cargo's ability to protect against multiple concurrent invocations of - Cargo installing at the same time. +{{#option "`-f`" "`--force`" }} +Force overwriting existing crates or binaries. This can be used if a package +has installed a binary with the same name as another package. This is also +useful if something has changed on the system that you want to rebuild with, +such as a newer version of `rustc`. +{{/option}} -*--bin* _NAME_...:: - Install only the specified binary. +{{#option "`--no-track`" }} +By default, Cargo keeps track of the installed packages with a metadata file +stored in the installation root directory. This flag tells Cargo not to use or +create that file. With this flag, Cargo will refuse to overwrite any existing +files unless the `--force` flag is used. This also disables Cargo's ability to +protect against multiple concurrent invocations of Cargo installing at the +same time. +{{/option}} -*--bins*:: - Install all binaries. +{{#option "`--bin` _name_..." }} +Install only the specified binary. +{{/option}} -*--example* _NAME_...:: - Install only the specified example. +{{#option "`--bins`" }} +Install all binaries. +{{/option}} -*--examples*:: - Install all examples. +{{#option "`--example` _name_..." }} +Install only the specified example. +{{/option}} -*--root* _DIR_:: - Directory to install packages into. +{{#option "`--examples`" }} +Install all examples. +{{/option}} -include::options-registry.adoc[] +{{#option "`--root` _dir_" }} +Directory to install packages into. +{{/option}} -include::options-index.adoc[] +{{> options-registry }} -include::options-features.adoc[] +{{> options-index }} -=== Compilation Options +{{/options}} -include::options-target-triple.adoc[] +{{> section-features }} -include::options-target-dir.adoc[] +### Compilation Options -*--debug*:: - Build with the `dev` profile instead the `release` profile. +{{#options}} -=== Manifest Options +{{> options-target-triple }} -include::options-locked.adoc[] +{{> options-target-dir }} -=== Miscellaneous Options +{{#option "`--debug`" }} +Build with the `dev` profile instead the `release` profile. +{{/option}} -include::options-jobs.adoc[] +{{/options}} -=== Display Options +### Manifest Options -include::options-display.adoc[] +{{#options}} +{{> options-locked }} +{{/options}} -=== Common Options +### Miscellaneous Options -include::options-common.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-environment.adoc[] +### Display Options -include::section-exit-status.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -== EXAMPLES +{{> section-options-common }} -. Install or upgrade a package from crates.io: +{{> section-environment }} - cargo install ripgrep +{{> section-exit-status }} -. Install or reinstall the package in the current directory: +## EXAMPLES - cargo install --path . +1. Install or upgrade a package from crates.io: -. View the list of installed packages: + cargo install ripgrep - cargo install --list +2. Install or reinstall the package in the current directory: -== SEE ALSO -man:cargo[1], man:cargo-uninstall[1], man:cargo-search[1], man:cargo-publish[1] + cargo install --path . + +3. View the list of installed packages: + + cargo install --list + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-uninstall" 1}}, {{man "cargo-search" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-locate-project.md b/src/doc/man/cargo-locate-project.md index adfc7a39ebf..349e63c5e8d 100644 --- a/src/doc/man/cargo-locate-project.md +++ b/src/doc/man/cargo-locate-project.md @@ -1,46 +1,46 @@ -= cargo-locate-project(1) -:idprefix: cargo_locate-project_ -:doctype: manpage +# cargo-locate-project(1) -== NAME +## NAME cargo-locate-project - Print a JSON representation of a Cargo.toml file's location -== SYNOPSIS +## SYNOPSIS -`cargo locate-project [_OPTIONS_]` +`cargo locate-project` [_options_] -== DESCRIPTION +## 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 +See also {{man "cargo-metadata" 1}} which is capable of returning the path to a workspace root. -== OPTIONS +## OPTIONS -=== Display Options +### Display Options -include::options-display.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -=== Manifest Options +### Manifest Options -include::options-manifest-path.adoc[] +{{#options}} +{{> options-manifest-path }} +{{/options}} -=== Common Options +{{> section-options-common }} -include::options-common.adoc[] +{{> section-environment }} -include::section-environment.adoc[] +{{> section-exit-status }} -include::section-exit-status.adoc[] +## EXAMPLES -== EXAMPLES +1. Display the path to the manifest based on the current directory: -. Display the path to the manifest based on the current directory: + cargo locate-project - cargo locate-project - -== SEE ALSO -man:cargo[1], man:cargo-metadata[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-login.md b/src/doc/man/cargo-login.md index 2d3a8e7527b..0e361ab74a0 100644 --- a/src/doc/man/cargo-login.md +++ b/src/doc/man/cargo-login.md @@ -1,51 +1,51 @@ -= cargo-login(1) -:idprefix: cargo_login_ -:doctype: manpage +# cargo-login(1) -== NAME +## NAME cargo-login - Save an API token from the registry locally -== SYNOPSIS +## SYNOPSIS -`cargo login [_OPTIONS_] [_TOKEN_]` +`cargo login` [_options_] [_token_] -== DESCRIPTION +## 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 +authentication, such as {{man "cargo-publish" 1}}, will be automatically authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` defaults to `.cargo` in your home directory. -If the _TOKEN_ argument is not specified, it will be read from stdin. +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. +The API token for crates.io may be retrieved from . Take care to keep the token secret, it should not be shared with anyone else. -== OPTIONS +## OPTIONS -=== Login Options +### Login Options -include::options-registry.adoc[] +{{#options}} +{{> options-registry }} +{{/options}} -=== Display Options +### Display Options -include::options-display.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -=== Common Options +{{> section-options-common }} -include::options-common.adoc[] +{{> section-environment }} -include::section-environment.adoc[] +{{> section-exit-status }} -include::section-exit-status.adoc[] +## EXAMPLES -== EXAMPLES +1. Save the API token to disk: -. Save the API token to disk: + cargo login - cargo login - -== SEE ALSO -man:cargo[1], man:cargo-publish[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-metadata.md b/src/doc/man/cargo-metadata.md index 09a865a7ad9..45c8b04f37e 100644 --- a/src/doc/man/cargo-metadata.md +++ b/src/doc/man/cargo-metadata.md @@ -1,17 +1,15 @@ -= cargo-metadata(1) -:idprefix: cargo_metadata_ -:doctype: manpage +# cargo-metadata(1) :source-highlighter: highlightjs -== NAME +## NAME cargo-metadata - Machine-readable metadata about the current package -== SYNOPSIS +## SYNOPSIS -`cargo metadata [_OPTIONS_]` +`cargo metadata` [_options_] -== DESCRIPTION +## DESCRIPTION Output JSON to stdout containing information about the workspace members and resolved dependencies of the current package. @@ -19,15 +17,14 @@ resolved dependencies of the current package. It is recommended to include the `--format-version` flag to future-proof your code to ensure the output is in the format you are expecting. -See the link:https://crates.io/crates/cargo_metadata[cargo_metadata crate] +See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata) for a Rust API for reading the metadata. -== OUTPUT FORMAT +## OUTPUT FORMAT The output has the following format: -[source,javascript] ----- +```javascript { /* Array of all packages in the workspace. It also includes all feature-enabled dependencies unless --no-deps is used. @@ -281,53 +278,62 @@ The output has the following format: } } } ----- +```` -== OPTIONS +## OPTIONS -=== Output Options +### Output Options -*--no-deps*:: - Output information only about the workspace members and don't fetch - dependencies. +{{#options}} -*--format-version* _VERSION_:: - Specify the version of the output format to use. Currently `1` is the only - possible value. +{{#option "`--no-deps`" }} +Output information only about the workspace members and don't fetch +dependencies. +{{/option}} + +{{#option "`--format-version` _version_" }} +Specify the version of the output format to use. Currently `1` is the only +possible value. +{{/option}} + +{{#option "`--filter-platform` _triple_" }} +This filters the `resolve` output to only include dependencies for the +given target triple. Without this flag, the resolve includes all targets. -*--filter-platform* _TRIPLE_:: - This filters the `resolve` output to only include dependencies for the - given target triple. Without this flag, the resolve includes all targets. -+ Note that the dependencies listed in the "packages" array still includes all dependencies. Each package definition is intended to be an unaltered reproduction of the information within `Cargo.toml`. +{{/option}} -include::options-features.adoc[] +{{/options}} -=== Display Options +{{> section-features }} -include::options-display.adoc[] +### Display Options -=== Manifest Options +{{#options}} +{{> options-display }} +{{/options}} -include::options-manifest-path.adoc[] +### Manifest Options -include::options-locked.adoc[] +{{#options}} +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Output JSON about the current package: +1. Output JSON about the current package: - cargo metadata --format-version=1 + cargo metadata --format-version=1 -== SEE ALSO -man:cargo[1] +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-new.md b/src/doc/man/cargo-new.md index 6587a378960..a8b039fc26b 100644 --- a/src/doc/man/cargo-new.md +++ b/src/doc/man/cargo-new.md @@ -1,50 +1,48 @@ -= cargo-new(1) -:idprefix: cargo_new_ -:doctype: manpage +# cargo-new(1) -== NAME +## NAME cargo-new - Create a new Cargo package -== SYNOPSIS +## SYNOPSIS -`cargo new [_OPTIONS_] _PATH_` +`cargo new` [_options_] _path_ -== DESCRIPTION +## 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[] +{{> description-new-authors }} -See man:cargo-init[1] for a similar command which will create a new manifest +See {{man "cargo-init" 1}} for a similar command which will create a new manifest in an existing directory. -== OPTIONS +## OPTIONS -=== New Options +### New Options -include::options-new.adoc[] +{{> options-new }} -=== Display Options +### Display Options -include::options-display.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -=== Common Options +{{> section-options-common }} -include::options-common.adoc[] +{{> section-environment }} -include::section-environment.adoc[] +{{> section-exit-status }} -include::section-exit-status.adoc[] +## EXAMPLES -== EXAMPLES +1. Create a binary Cargo package in the given directory: -. Create a binary Cargo package in the given directory: + cargo new foo - cargo new foo - -== SEE ALSO -man:cargo[1], man:cargo-init[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-init" 1}} diff --git a/src/doc/man/cargo-owner.md b/src/doc/man/cargo-owner.md index 63e6e309d1b..3787a4de045 100644 --- a/src/doc/man/cargo-owner.md +++ b/src/doc/man/cargo-owner.md @@ -1,80 +1,81 @@ -= cargo-owner(1) -:idprefix: cargo_owner_ -:doctype: manpage +# cargo-owner(1) -== NAME +## NAME cargo-owner - Manage the owners of a crate on the registry -== SYNOPSIS +## SYNOPSIS -[%hardbreaks] -`cargo owner [_OPTIONS_] --add _LOGIN_ [_CRATE_]` -`cargo owner [_OPTIONS_] --remove _LOGIN_ [_CRATE_]` -`cargo owner [_OPTIONS_] --list [_CRATE_]` +`cargo owner` [_options_] `--add` _login_ [_crate_]\ +`cargo owner` [_options_] `--remove` _login_ [_crate_]\ +`cargo owner` [_options_] `--list` [_crate_] -== DESCRIPTION +## 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]. +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 +See [the reference](../reference/publishing.html#cargo-owner) for more information about owners and publishing. -== OPTIONS +## OPTIONS -=== Owner Options +### Owner Options -*-a*:: -*--add* _LOGIN_...:: - Invite the given user or team as an owner. +{{#options}} -*-r*:: -*--remove* _LOGIN_...:: - Remove the given user or team as an owner. +{{#option "`-a`" "`--add` _login_..." }} +Invite the given user or team as an owner. +{{/option}} -*-l*:: -*--list*:: - List owners of a crate. +{{#option "`-r`" "`--remove` _login_..." }} +Remove the given user or team as an owner. +{{/option}} -include::options-token.adoc[] +{{#option "`-l`" "`--list`" }} +List owners of a crate. +{{/option}} -include::options-index.adoc[] +{{> options-token }} -include::options-registry.adoc[] +{{> options-index }} -=== Display Options +{{> options-registry }} -include::options-display.adoc[] +{{/options}} -=== Common Options +### Display Options -include::options-common.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -include::section-environment.adoc[] +{{> section-options-common }} -include::section-exit-status.adoc[] +{{> section-environment }} -== EXAMPLES +{{> section-exit-status }} -. List owners of a package: +## EXAMPLES - cargo owner --list foo +1. List owners of a package: -. Invite an owner to a package: + cargo owner --list foo - cargo owner --add username foo +2. Invite an owner to a package: -. Remove an owner from a package: + cargo owner --add username foo - cargo owner --remove username foo +3. Remove an owner from a package: -== SEE ALSO -man:cargo[1], man:cargo-login[1], man:cargo-publish[1] + cargo owner --remove username foo + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-login" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-package.md b/src/doc/man/cargo-package.md index ba1c1b5d69a..a825299b0cf 100644 --- a/src/doc/man/cargo-package.md +++ b/src/doc/man/cargo-package.md @@ -1,102 +1,117 @@ -= cargo-package(1) -:idprefix: cargo_package_ -:doctype: manpage -:actionverb: Package +# cargo-package(1) +{{*set actionverb="Package"}} -== NAME +## NAME cargo-package - Assemble the local package into a distributable tarball -== SYNOPSIS +## SYNOPSIS -`cargo package [_OPTIONS_]` +`cargo package` [_options_] -== DESCRIPTION +## 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. +1. Load and check the current workspace, performing some basic checks. - Path dependencies are not allowed unless they have a version key. Cargo will ignore the path key for dependencies in published packages. `dev-dependencies` do not have this restriction. -. Create the compressed `.crate` file. +2. Create the compressed `.crate` file. - The original `Cargo.toml` file is rewritten and normalized. - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the manifest. - `Cargo.lock` is automatically included if the package contains an - executable binary or example target. man:cargo-install[1] will use the + executable binary or example target. {{man "cargo-install" 1}} will use the packaged lock file if the `--locked` flag is used. - A `.cargo_vcs_info.json` file is included that contains information about the current VCS checkout hash if available (not included with `--allow-dirty`). -. Extract the `.crate` file and build it to verify it can build. +3. Extract the `.crate` file and build it to verify it can build. - This will rebuild your package from scratch to ensure that it can be built from a pristine state. The `--no-verify` flag can be used to skip this step. -. Check that build scripts did not modify any source files. +4. Check that build scripts did not modify any source files. The list of files included can be controlled with the `include` and `exclude` fields in the manifest. -See linkcargo:reference/publishing.html[the reference] for more details about +See [the reference](../reference/publishing.html) for more details about packaging and publishing. -== OPTIONS +## OPTIONS -=== Package Options +### Package Options -*-l*:: -*--list*:: - Print files included in a package without making one. +{{#options}} -*--no-verify*:: - Don't verify the contents by building them. +{{#option "`-l`" "`--list`" }} +Print files included in a package without making one. +{{/option}} -*--no-metadata*:: - Ignore warnings about a lack of human-usable metadata (such as the - description or the license). +{{#option "`--no-verify`" }} +Don't verify the contents by building them. +{{/option}} -*--allow-dirty*:: - Allow working directories with uncommitted VCS changes to be packaged. +{{#option "`--no-metadata`" }} +Ignore warnings about a lack of human-usable metadata (such as the description +or the license). +{{/option}} -=== Compilation Options +{{#option "`--allow-dirty`" }} +Allow working directories with uncommitted VCS changes to be packaged. +{{/option}} -include::options-target-triple.adoc[] +{{/options}} -include::options-target-dir.adoc[] +### Compilation Options -include::options-features.adoc[] +{{#options}} -=== Manifest Options +{{> options-target-triple }} -include::options-manifest-path.adoc[] +{{> options-target-dir }} -include::options-locked.adoc[] +{{/options}} -=== Miscellaneous Options +{{> section-features }} -include::options-jobs.adoc[] +### Manifest Options -=== Display Options +{{#options}} -include::options-display.adoc[] +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} -include::options-common.adoc[] +{{/options}} -include::section-environment.adoc[] +### Miscellaneous Options -include::section-exit-status.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -== EXAMPLES +### Display Options -. Create a compressed `.crate` file of the current package: +{{#options}} +{{> options-display }} +{{/options}} - cargo package +{{> section-options-common }} -== SEE ALSO -man:cargo[1], man:cargo-publish[1] +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Create a compressed `.crate` file of the current package: + + cargo package + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-pkgid.md b/src/doc/man/cargo-pkgid.md index 98ff9dd9d89..12f8cacc8c4 100644 --- a/src/doc/man/cargo-pkgid.md +++ b/src/doc/man/cargo-pkgid.md @@ -1,21 +1,19 @@ -= cargo-pkgid(1) -:idprefix: cargo_pkgid_ -:doctype: manpage +# cargo-pkgid(1) -== NAME +## NAME cargo-pkgid - Print a fully qualified package specification -== SYNOPSIS +## SYNOPSIS -`cargo pkgid [_OPTIONS_] [_SPEC_]` +`cargo pkgid` [_options_] [_spec_] -== DESCRIPTION +## DESCRIPTION -Given a _SPEC_ argument, print out the fully qualified package ID specifier +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 +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 @@ -23,72 +21,65 @@ 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 +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 +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` -|__NAME__ -|`bitflags` +## OPTIONS -|__NAME__``:``__VERSION__ -|`bitflags:1.0.4` +### Package Selection -|__URL__ -|`https://github.com/rust-lang/cargo` +{{#options}} -|__URL__``#``__VERSION__ -|`https://github.com/rust-lang/cargo#0.33.0` +{{#option "`-p` _spec_" "`--package` _spec_" }} +Get the package ID for the given package instead of the current package. +{{/option}} -|__URL__``#``__NAME__ -|`https://github.com/rust-lang/crates.io-index#bitflags` +{{/options}} -|__URL__``#``__NAME__``:``__VERSION__ -|`https://github.com/rust-lang/cargo#crates-io:0.21.0` -|=== +### Display Options -== OPTIONS +{{#options}} +{{> options-display }} +{{/options}} -=== Package Selection +### Manifest Options -*-p* _SPEC_:: -*--package* _SPEC_:: - Get the package ID for the given package instead of the current package. +{{#options}} -=== Display Options +{{> options-manifest-path }} -include::options-display.adoc[] +{{> options-locked }} -=== Manifest Options +{{/options}} -include::options-manifest-path.adoc[] +{{> section-options-common }} -include::options-locked.adoc[] +{{> section-environment }} -=== Common Options +{{> section-exit-status }} -include::options-common.adoc[] +## EXAMPLES -include::section-environment.adoc[] +1. Retrieve package specification for `foo` package: -include::section-exit-status.adoc[] + cargo pkgid foo -== EXAMPLES +2. Retrieve package specification for version 1.0.0 of `foo`: -. Retrieve package specification for `foo` package: + cargo pkgid foo:1.0.0 - cargo pkgid foo +3. Retrieve package specification for `foo` from crates.io: -. Retrieve package specification for version 1.0.0 of `foo`: + cargo pkgid https://github.com/rust-lang/crates.io-index#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] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-publish.md b/src/doc/man/cargo-publish.md index f63c38ba628..8267a8d4888 100644 --- a/src/doc/man/cargo-publish.md +++ b/src/doc/man/cargo-publish.md @@ -1,90 +1,105 @@ -= cargo-publish(1) -:idprefix: cargo_publish_ -:doctype: manpage -:actionverb: Publish +# cargo-publish(1) +{{*set actionverb="Publish"}} -== NAME +## NAME cargo-publish - Upload a package to the registry -== SYNOPSIS +## SYNOPSIS -`cargo publish [_OPTIONS_]` +`cargo publish` [_options_] -== DESCRIPTION +## 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 +registry. The default registry is . This performs the following steps: -. Performs a few checks, including: - - Checks the `package.publish` key in the manifest for restrictions on which - registries you are allowed to publish to. -. Create a `.crate` file by following the steps in man:cargo-package[1]. -. Upload the crate to the registry. Note that the server will perform - additional checks on the crate. +1. Performs a few checks, including: + - Checks the `package.publish` key in the manifest for restrictions on + which registries you are allowed to publish to. +2. Create a `.crate` file by following the steps in {{man "cargo-package" 1}}. +3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. This command requires you to be authenticated with either the `--token` option -or using man:cargo-login[1]. +or using {{man "cargo-login" 1}}. -See linkcargo:reference/publishing.html[the reference] for more details about +See [the reference](../reference/publishing.html) for more details about packaging and publishing. -== OPTIONS +## OPTIONS -=== Publish Options +### Publish Options -*--dry-run*:: - Perform all checks without uploading. +{{#options}} -include::options-token.adoc[] +{{#option "`--dry-run`" }} +Perform all checks without uploading. +{{/option}} -*--no-verify*:: - Don't verify the contents by building them. +{{> options-token }} -*--allow-dirty*:: - Allow working directories with uncommitted VCS changes to be packaged. +{{#option "`--no-verify`" }} +Don't verify the contents by building them. +{{/option}} -include::options-index.adoc[] +{{#option "`--allow-dirty`" }} +Allow working directories with uncommitted VCS changes to be packaged. +{{/option}} -include::options-registry.adoc[] +{{> options-index }} -=== Compilation Options +{{> options-registry }} -include::options-target-triple.adoc[] +{{/options}} -include::options-target-dir.adoc[] +### Compilation Options -include::options-features.adoc[] +{{#options}} -=== Manifest Options +{{> options-target-triple }} -include::options-manifest-path.adoc[] +{{> options-target-dir }} -include::options-locked.adoc[] +{{/options}} -=== Miscellaneous Options +{{> section-features }} -include::options-jobs.adoc[] +### Manifest Options -=== Display Options +{{#options}} -include::options-display.adoc[] +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} -include::options-common.adoc[] +{{/options}} -include::section-environment.adoc[] +### Miscellaneous Options -include::section-exit-status.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -== EXAMPLES +### Display Options -. Publish the current package: +{{#options}} +{{> options-display }} +{{/options}} - cargo publish +{{> section-options-common }} -== SEE ALSO -man:cargo[1], man:cargo-package[1], man:cargo-login[1] +{{> section-environment }} + +{{> section-exit-status }} + +## EXAMPLES + +1. Publish the current package: + + cargo publish + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-package" 1}}, {{man "cargo-login" 1}} diff --git a/src/doc/man/cargo-run.md b/src/doc/man/cargo-run.md index 8aa64e75776..bd545613c90 100644 --- a/src/doc/man/cargo-run.md +++ b/src/doc/man/cargo-run.md @@ -1,17 +1,15 @@ -= cargo-run(1) -:idprefix: cargo_run_ -:doctype: manpage -:actionverb: Run +# cargo-run(1) +{{*set actionverb="Run"}} -== NAME +## NAME cargo-run - Run the current package -== SYNOPSIS +## SYNOPSIS -`cargo run [_OPTIONS_] [-- _ARGS_]` +`cargo run` [_options_] [`--` _args_] -== DESCRIPTION +## DESCRIPTION Run a binary or example of the local package. @@ -19,72 +17,90 @@ 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 +## OPTIONS -=== Package Selection +{{> section-options-package }} -include::options-package.adoc[] - -=== Target Selection +### Target Selection When no target selection options are given, `cargo run` will run the binary target. If there are multiple binary targets, you must pass a target flag to choose one. Or, the `default-run` field may be specified in the `[package]` section of `Cargo.toml` to choose the name of the binary to run by default. -*--bin* _NAME_:: - Run the specified binary. +{{#options}} + +{{#option "`--bin` _name_" }} +Run the specified binary. +{{/option}} + +{{#option "`--example` _name_" }} +Run the specified example. +{{/option}} + +{{/options}} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} -*--example* _NAME_:: - Run the specified example. +{{> options-release }} -include::options-features.adoc[] +{{/options}} -=== Compilation Options +### Output Options -include::options-target-triple.adoc[] +{{#options}} +{{> options-target-dir }} +{{/options}} -include::options-release.adoc[] +### Display Options -=== Output Options +{{#options}} -include::options-target-dir.adoc[] +{{> options-display }} -=== Display Options +{{> options-message-format }} -include::options-display.adoc[] +{{/options}} -include::options-message-format.adoc[] +### Manifest Options -=== Manifest Options +{{#options}} -include::options-manifest-path.adoc[] +{{> options-manifest-path }} -include::options-locked.adoc[] +{{> options-locked }} -=== Common Options +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -=== Miscellaneous Options +### Miscellaneous Options -include::options-jobs.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-profiles.adoc[] +{{> section-profiles }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Build the local package and run its main target (assuming only one binary): +1. Build the local package and run its main target (assuming only one binary): - cargo run + cargo run -. Run an example with extra arguments: +2. Run an example with extra arguments: - cargo run --example exname -- --exoption exarg1 exarg2 + cargo run --example exname -- --exoption exarg1 exarg2 -== SEE ALSO -man:cargo[1], man:cargo-build[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/src/doc/man/cargo-rustc.md b/src/doc/man/cargo-rustc.md index e3ef3e5fc72..c7f74573bee 100644 --- a/src/doc/man/cargo-rustc.md +++ b/src/doc/man/cargo-rustc.md @@ -1,94 +1,104 @@ -= cargo-rustc(1) -:idprefix: cargo_rustc_ -:doctype: manpage -:actionverb: Build +# cargo-rustc(1) +{{*set actionverb="Build"}} -== NAME +## NAME cargo-rustc - Compile the current package, and pass extra options to the compiler -== SYNOPSIS +## SYNOPSIS -`cargo rustc [_OPTIONS_] [-- _ARGS_]` +`cargo rustc` [_options_] [`--` _args_] -== DESCRIPTION +## 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 +_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. +_args_ will simply be added to the compiler invocation. -See https://doc.rust-lang.org/rustc/index.html for documentation on rustc +See for documentation on rustc flags. -include::description-one-target.adoc[] +{{> description-one-target }} To pass flags to all compiler processes spawned by Cargo, use the `RUSTFLAGS` -linkcargo:reference/environment-variables.html[environment variable] or the -`build.rustflags` linkcargo:reference/config.html[config value]. +[environment variable](../reference/environment-variables.html) or the +`build.rustflags` [config value](../reference/config.html). -== OPTIONS +## OPTIONS -=== Package Selection +{{> section-options-package }} -include::options-package.adoc[] - -=== Target Selection +### 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[] +{{> options-targets }} + +{{> section-features }} + +### Compilation Options + +{{#options}} + +{{> options-target-triple }} + +{{> options-release }} -include::options-features.adoc[] +{{/options}} -=== Compilation Options +### Output Options -include::options-target-triple.adoc[] +{{#options}} +{{> options-target-dir }} +{{/options}} -include::options-release.adoc[] +### Display Options -=== Output Options +{{#options}} -include::options-target-dir.adoc[] +{{> options-display }} -=== Display Options +{{> options-message-format }} -include::options-display.adoc[] +{{/options}} -include::options-message-format.adoc[] +### Manifest Options -=== Manifest Options +{{#options}} -include::options-manifest-path.adoc[] +{{> options-manifest-path }} -include::options-locked.adoc[] +{{> options-locked }} -=== Common Options +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -=== Miscellaneous Options +### Miscellaneous Options -include::options-jobs.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-profiles.adoc[] +{{> section-profiles }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Check if your package (not including dependencies) uses unsafe code: +1. Check if your package (not including dependencies) uses unsafe code: - cargo rustc --lib -- -D 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: +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 + cargo rustc --lib -- -Z print-type-sizes -== SEE ALSO -man:cargo[1], man:cargo-build[1], man:rustc[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-build" 1}}, {{man "rustc" 1}} diff --git a/src/doc/man/cargo-rustdoc.md b/src/doc/man/cargo-rustdoc.md index 96f37252aaa..958aa13c217 100644 --- a/src/doc/man/cargo-rustdoc.md +++ b/src/doc/man/cargo-rustdoc.md @@ -1,98 +1,108 @@ -= cargo-rustdoc(1) -:idprefix: cargo_rustdoc_ -:doctype: manpage -:actionverb: Document +# cargo-rustdoc(1) +{{*set actionverb="Document"}} -== NAME +## NAME cargo-rustdoc - Build a package's documentation, using specified custom flags -== SYNOPSIS +## SYNOPSIS -`cargo rustdoc [_OPTIONS_] [-- _ARGS_]` +`cargo rustdoc` [_options_] [`--` _args_] -== DESCRIPTION +## 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 +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 +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 +See for documentation on rustdoc flags. -include::description-one-target.adoc[] +{{> description-one-target }} To pass flags to all rustdoc processes spawned by Cargo, use the -`RUSTDOCFLAGS` linkcargo:reference/environment-variables.html[environment variable] -or the `build.rustdocflags` linkcargo:reference/config.html[config value]. +`RUSTDOCFLAGS` [environment variable](../reference/environment-variables.html) +or the `build.rustdocflags` [config value](../reference/config.html). -== OPTIONS +## OPTIONS -=== Documentation Options +### Documentation Options -*--open*:: - Open the docs in a browser after building them. This will use your default - browser unless you define another one in the `BROWSER` environment - variable. +{{#options}} -=== Package Selection +{{#option "`--open`" }} +Open the docs in a browser after building them. This will use your default +browser unless you define another one in the `BROWSER` environment variable. +{{/option}} -include::options-package.adoc[] +{{/options}} -=== Target Selection +{{> section-options-package }} + +### Target Selection When no target selection options are given, `cargo rustdoc` will document all binary and library targets of the selected package. The binary will be skipped if its name is the same as the lib target. Binaries are skipped if they have `required-features` that are missing. -include::options-targets.adoc[] +{{> options-targets }} + +{{> section-features }} -include::options-features.adoc[] +### Compilation Options -=== Compilation Options +{{#options}} -include::options-target-triple.adoc[] +{{> options-target-triple }} -include::options-release.adoc[] +{{> options-release }} -=== Output Options +{{/options}} -include::options-target-dir.adoc[] +### Output Options -=== Display Options +{{#options}} +{{> options-target-dir }} +{{/options}} -include::options-display.adoc[] +### Display Options -include::options-message-format.adoc[] +{{#options}} +{{> options-display }} -=== Manifest Options +{{> options-message-format }} +{{/options}} -include::options-manifest-path.adoc[] +### Manifest Options -include::options-locked.adoc[] +{{#options}} +{{> options-manifest-path }} -=== Common Options +{{> options-locked }} +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -=== Miscellaneous Options +### Miscellaneous Options -include::options-jobs.adoc[] +{{#options}} +{{> options-jobs }} +{{/options}} -include::section-profiles.adoc[] +{{> section-profiles }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Build documentation with custom CSS included from a given file: +1. Build documentation with custom CSS included from a given file: - cargo rustdoc --lib -- --extend-css extra.css + cargo rustdoc --lib -- --extend-css extra.css -== SEE ALSO -man:cargo[1], man:cargo-doc[1], man:rustdoc[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-doc" 1}}, {{man "rustdoc" 1}} diff --git a/src/doc/man/cargo-search.md b/src/doc/man/cargo-search.md index 4d51285928f..5c7bcac3c2f 100644 --- a/src/doc/man/cargo-search.md +++ b/src/doc/man/cargo-search.md @@ -1,49 +1,52 @@ -= cargo-search(1) -:idprefix: cargo_search_ -:doctype: manpage +# cargo-search(1) -== NAME +## NAME cargo-search - Search packages in crates.io -== SYNOPSIS +## SYNOPSIS -`cargo search [_OPTIONS_] [_QUERY_...]` +`cargo search` [_options_] [_query_...] -== DESCRIPTION +## DESCRIPTION -This performs a textual search for crates on https://crates.io. The matching +This performs a textual search for crates on . The matching crates will be displayed along with their description in TOML format suitable for copying into a `Cargo.toml` manifest. -== OPTIONS +## OPTIONS -=== Search Options +### Search Options -*--limit* _LIMIT_:: - Limit the number of results (default: 10, max: 100). +{{#options}} -include::options-index.adoc[] +{{#option "`--limit` _limit_" }} +Limit the number of results (default: 10, max: 100). +{{/option}} -include::options-registry.adoc[] +{{> options-index }} -=== Display Options +{{> options-registry }} -include::options-display.adoc[] +{{/options}} -=== Common Options +### Display Options -include::options-common.adoc[] +{{#options}} +{{> options-display }} +{{/options}} -include::section-environment.adoc[] +{{> section-options-common }} -include::section-exit-status.adoc[] +{{> section-environment }} -== EXAMPLES +{{> section-exit-status }} -. Search for a package from crates.io: +## EXAMPLES - cargo search serde +1. Search for a package from crates.io: -== SEE ALSO -man:cargo[1], man:cargo-install[1], man:cargo-publish[1] + cargo search serde + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-install" 1}}, {{man "cargo-publish" 1}} diff --git a/src/doc/man/cargo-test.md b/src/doc/man/cargo-test.md index ba338b12bfb..732ae14b10c 100644 --- a/src/doc/man/cargo-test.md +++ b/src/doc/man/cargo-test.md @@ -1,18 +1,16 @@ -= cargo-test(1) -:idprefix: cargo_test_ -:doctype: manpage -:actionverb: Test -:nouns: tests +# cargo-test(1) +{{*set actionverb="Test"}} +{{*set nouns="tests"}} -== NAME +## NAME cargo-test - Execute unit and integration tests of a package -== SYNOPSIS +## SYNOPSIS -`cargo test [_OPTIONS_] [TESTNAME] [-- _TEST-OPTIONS_]` +`cargo test` [_options_] [_testname_] [`--` _test-options_] -== DESCRIPTION +## DESCRIPTION Compile and execute unit and integration tests. @@ -21,7 +19,7 @@ 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`. +output of `cargo test -- --help`. As an example, this will filter for tests with `foo` in their name and run them on 3 threads in parallel: @@ -30,7 +28,7 @@ on 3 threads in parallel: Tests are built with the `--test` option to `rustc` which creates an executable with a `main` function that automatically runs all functions -annotated with the `\#[test]` attribute in multiple threads. `#[bench]` +annotated with the `#[test]` attribute in multiple threads. `#[bench]` annotated functions will also be run with one iteration to verify that they are functional. @@ -40,20 +38,18 @@ function to handle running tests. Documentation tests are also run by default, which is handled by `rustdoc`. It extracts code samples from documentation comments and executes them. See the -link:https://doc.rust-lang.org/rustdoc/[rustdoc book] for more information on +[rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information on writing doc tests. -== OPTIONS +## OPTIONS -=== Test Options +### Test Options -include::options-test.adoc[] +{{> options-test }} -=== Package Selection +{{> section-package-selection }} -include::options-packages.adoc[] - -=== Target Selection +### Target Selection When no target selection options are given, `cargo test` will build the following targets of the selected packages: @@ -78,31 +74,42 @@ library in the manifest. Binary targets are automatically built if there is an integration test or benchmark. This allows an integration test to execute the binary to exercise -and test its behavior. The `CARGO_BIN_EXE_` -linkcargo:reference/environment-variables.html#environment-variables-cargo-sets-for-crates[environment variable] +and test its behavior. The `CARGO_bin_EXE_` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) is set when the integration test is built so that it can use the -link:https://doc.rust-lang.org/std/macro.env.html[`env` macro] to locate the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the executable. -include::options-targets.adoc[] +{{> options-targets }} + +{{#options}} + +{{#option "`--doc`" }} +Test only the library's documentation. This cannot be mixed with other +target options. +{{/option}} + +{{/options}} + +{{> section-features }} -*--doc*:: - Test only the library's documentation. This cannot be mixed with other - target options. +### Compilation Options -include::options-features.adoc[] +{{#options}} -=== Compilation Options +{{> options-target-triple }} -include::options-target-triple.adoc[] +{{> options-release }} -include::options-release.adoc[] +{{/options}} -=== Output Options +### Output Options -include::options-target-dir.adoc[] +{{#options}} +{{> options-target-dir }} +{{/options}} -=== Display Options +### Display Options By default the Rust test harness hides output from test execution to keep results readable. Test output can be recovered (e.g., for debugging) by passing @@ -110,21 +117,27 @@ results readable. Test output can be recovered (e.g., for debugging) by passing cargo test -- --nocapture -include::options-display.adoc[] +{{#options}} -include::options-message-format.adoc[] +{{> options-display }} -=== Manifest Options +{{> options-message-format }} -include::options-manifest-path.adoc[] +{{/options}} -include::options-locked.adoc[] +### Manifest Options -=== Common Options +{{#options}} -include::options-common.adoc[] +{{> options-manifest-path }} -=== Miscellaneous Options +{{> options-locked }} + +{{/options}} + +{{> section-options-common }} + +### Miscellaneous Options The `--jobs` argument affects the building of the test executable but does not affect how many threads are used when running the tests. The Rust test harness @@ -132,9 +145,13 @@ includes an option to control the number of threads used: cargo test -j 2 -- --test-threads=2 -include::options-jobs.adoc[] +{{#options}} + +{{> options-jobs }} + +{{/options}} -include::section-profiles.adoc[] +{{> section-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 @@ -144,23 +161,23 @@ 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[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Execute all the unit and integration tests of the current package: +1. Execute all the unit and integration tests of the current package: - cargo test + cargo test -. Run only tests whose names match against a filter string: +2. Run only tests whose names match against a filter string: - cargo test name_filter + cargo test name_filter -. Run only a specific test within a specific integration test: +3. Run only a specific test within a specific integration test: - cargo test --test int_test_name -- modname::test_name + cargo test --test int_test_name -- modname::test_name -== SEE ALSO -man:cargo[1], man:cargo-bench[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-bench" 1}} diff --git a/src/doc/man/cargo-tree.md b/src/doc/man/cargo-tree.md index 86b3276a48e..dc691e3461e 100644 --- a/src/doc/man/cargo-tree.md +++ b/src/doc/man/cargo-tree.md @@ -1,23 +1,21 @@ -= cargo-tree(1) -:idprefix: cargo_tree_ -:doctype: manpage -:actionverb: Display -:noall: true +# cargo-tree(1) +{{*set actionverb="Display"}} +{{*set noall=true}} -== NAME +## NAME cargo-tree - Display a tree visualization of a dependency graph -== SYNOPSIS +## SYNOPSIS -`cargo tree [_OPTIONS_]` +`cargo tree` [_options_] -== DESCRIPTION +## DESCRIPTION This command will display a tree of dependencies to the terminal. An example of a simple project that depends on the "rand" package: ----- +``` myproject v0.1.0 (/myproject) └── rand v0.7.3 ├── getrandom v0.1.14 @@ -31,7 +29,7 @@ myproject v0.1.0 (/myproject) └── rand_core v0.5.1 (*) [build-dependencies] └── cc v1.0.50 ----- +``` Packages marked with `(*)` have been "de-duplicated". The dependencies for the package have already been shown elswhere in the graph, and so are not @@ -41,187 +39,201 @@ The `-e` flag can be used to select the dependency kinds to display. The "features" kind changes the output to display the features enabled by each dependency. For example, `cargo tree -e features`: ----- +``` myproject v0.1.0 (/myproject) └── log feature "serde" └── log v0.4.8 ├── serde v1.0.106 └── cfg-if feature "default" └── cfg-if v0.1.10 ----- +``` In this tree, `myproject` depends on `log` with the `serde` feature. `log` in turn depends on `cfg-if` with "default" features. When using `-e features` it can be helpful to use `-i` flag to show how the features flow into a package. See the examples below for more detail. -== OPTIONS +## OPTIONS -=== Tree Options +### Tree Options + +{{#options}} + +{{#option "`-i` _spec_" "`--invert` _spec_" }} +Show the reverse dependencies for the given package. This flag will invert +the tree and display the packages that depend on the given package. -*-i* _SPEC_:: -*--invert* _SPEC_:: - Show the reverse dependencies for the given package. This flag will invert - the tree and display the packages that depend on the given package. -+ Note that in a workspace, by default it will only display the package's reverse dependencies inside the tree of the workspace member in the current directory. The `--workspace` flag can be used to extend it so that it will show the package's reverse dependencies across the entire workspace. The `-p` flag can be used to display the package's reverse dependencies only with the subtree of the package given to `-p`. +{{/option}} + +{{#option "`--no-dedupe`" }} +Do not de-duplicate repeated dependencies. Usually, when a package has already +displayed its dependencies, further occurrences will not re-display its +dependencies, and will include a `(*)` to indicate it has already been shown. +This flag will cause those duplicates to be repeated. +{{/option}} + +{{#option "`-d`" "`--duplicates`" }} +Show only dependencies which come in multiple versions (implies `--invert`). +When used with the `-p` flag, only shows duplicates within the subtree of the +given package. -*--no-dedupe*:: - Do not de-duplicate repeated dependencies. Usually, when a package has - already displayed its dependencies, further occurrences will not - re-display its dependencies, and will include a `(*)` to indicate it has - already been shown. This flag will cause those duplicates to be repeated. - -*-d*:: -*--duplicates*:: - Show only dependencies which come in multiple versions (implies - `--invert`). When used with the `-p` flag, only shows duplicates within - the subtree of the given package. -+ It can be beneficial for build times and executable sizes to avoid building that same package multiple times. This flag can help identify the offending packages. You can then investigate if the package that depends on the duplicate with the older version can be updated to the newer version so that only one instance is built. +{{/option}} + +{{#option "`-e` _kinds_" "`--edges` _kinds_" }} +The dependency kinds to display. Takes a comma separated list of values: + +- `all` — Show all edge kinds. +- `normal` — Show normal dependencies. +- `build` — Show build dependencies. +- `dev` — Show development dependencies. +- `features` — Show features enabled by each dependency. If this is the only + kind given, then it will automatically include the other dependency kinds. +- `no-normal` — Do not include normal dependencies. +- `no-build` — Do not include build dependencies. +- `no-dev` — Do not include development dependencies. -*-e* _KINDS_:: -*--edges* _KINDS_:: - The dependency kinds to display. Takes a comma separated list of values: -+ - - `all` — Show all edge kinds. - - `normal` — Show normal dependencies. - - `build` — Show build dependencies. - - `dev` — Show development dependencies. - - `features` — Show features enabled by each dependency. If this is - the only kind given, then it will automatically include the other - dependency kinds. - - `no-normal` — Do not include normal dependencies. - - `no-build` — Do not include build dependencies. - - `no-dev` — Do not include development dependencies. -+ The `no-` prefixed options cannot be mixed with the other dependency kinds. -+ + The default is `normal,build,dev`. +{{/option}} + +{{#option "`--target` _triple_" }} +Filter dependencies matching the given target-triple. The default is the host +platform. Use the value `all` to include *all* targets. +{{/option}} + +{{/options}} + +### Tree Formatting Options -*--target* _TRIPLE_:: - Filter dependencies matching the given target-triple. - The default is the host platform. Use the value `all` to include *all* - targets. +{{#options}} -=== Tree Formatting Options +{{#option "`--charset` _charset_" }} +Chooses the character set to use for the tree. Valid values are "utf8" or +"ascii". Default is "utf8". +{{/option}} -*--charset* _CHARSET_:: - Chooses the character set to use for the tree. Valid values are "utf8" or - "ascii". Default is "utf8". +{{#option "`-f` _format_" "`--format` _format_" }} +Set the format string for each package. The default is "{p}". -*-f* _FORMAT_:: -*--format* _FORMAT_:: - Set the format string for each package. The default is "{p}". -+ This is an arbitrary string which will be used to display each package. The following strings will be replaced with the corresponding value: -+ -- `{p}` — The package name. -- `{l}` — The package license. -- `{r}` — The package repository URL. + +- `{p}` — The package name. +- `{l}` — The package license. +- `{r}` — The package repository URL. - `{f}` — Comma-separated list of package features that are enabled. +{{/option}} + +{{#option "`--prefix` _prefix_" }} +Sets how each line is displayed. The _prefix_ value can be one of: + +- `indent` (default) — Shows each line indented as a tree. +- `depth` — Show as a list, with the numeric depth printed before each entry. +- `none` — Show as a flat list. +{{/option}} + +{{/options}} + +{{> section-package-selection }} + +### Manifest Options + +{{#options}} + +{{> options-manifest-path }} + +{{> options-locked }} -*--prefix* _PREFIX_:: - Sets how each line is displayed. The _PREFIX_ value can be one of: -+ -- `indent` (default) — Shows each line indented as a tree. -- `depth` — Show as a list, with the numeric depth printed before each entry. -- `none` — Show as a flat list. +{{/options}} -=== Package Selection +{{> section-features }} -include::options-packages.adoc[] +### Display Options -=== Manifest Options +{{#options}} -include::options-manifest-path.adoc[] +{{> options-display }} -include::options-features.adoc[] +{{/options}} -=== Display Options +{{> section-options-common }} -include::options-display.adoc[] +{{> section-environment }} -=== Common Options +{{> section-exit-status }} -include::options-common.adoc[] +## EXAMPLES -include::options-locked.adoc[] +1. Display the tree for the package in the current directory: -include::section-environment.adoc[] + cargo tree -include::section-exit-status.adoc[] +2. Display all the packages that depend on the `syn` package: -== EXAMPLES + cargo tree -i syn -. Display the tree for the package in the current directory: +3. Show the features enabled on each package: - cargo tree + cargo tree --format "{p} {f}" -. Display all the packages that depend on the `syn` package: +4. Show all packages that are built multiple times. This can happen if multiple + semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). - cargo tree -i syn + cargo tree -d -. Show the features enabled on each package: +5. Explain why features are enabled for the `syn` package: - cargo tree --format "{p} {f}" + cargo tree -e features -i syn -. Show all packages that are built multiple times. This can happen if multiple - semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). + The `-e features` flag is used to show features. The `-i` flag is used to + invert the graph so that it displays the packages that depend on `syn`. An + example of what this would display: - cargo tree -d + ``` + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + ``` -. Explain why features are enabled for the `syn` package: + To read this graph, you can follow the chain for each feature from the root + to see why it is included. For example, the "full" feature is added by the + `rustversion` crate which is included from `myproject` (with the default + features), and `myproject` is the package selected on the command-line. All + of the other `syn` features are added by the "default" feature ("quote" is + added by "printing" and "proc-macro", both of which are default features). - cargo tree -e features -i syn -+ -The `-e features` flag is used to show features. The `-i` flag is used to -invert the graph so that it displays the packages that depend on `syn`. An -example of what this would display: -+ ----- -syn v1.0.17 -├── syn feature "clone-impls" -│ └── syn feature "default" -│ └── rustversion v1.0.2 -│ └── rustversion feature "default" -│ └── myproject v0.1.0 (/myproject) -│ └── myproject feature "default" (command-line) -├── syn feature "default" (*) -├── syn feature "derive" -│ └── syn feature "default" (*) -├── syn feature "full" -│ └── rustversion v1.0.2 (*) -├── syn feature "parsing" -│ └── syn feature "default" (*) -├── syn feature "printing" -│ └── syn feature "default" (*) -├── syn feature "proc-macro" -│ └── syn feature "default" (*) -└── syn feature "quote" - ├── syn feature "printing" (*) - └── syn feature "proc-macro" (*) ----- -+ -To read this graph, you can follow the chain for each feature from the root to -see why it is included. For example, the "full" feature is added by the -`rustversion` crate which is included from `myproject` (with the default -features), and `myproject` is the package selected on the command-line. All -of the other `syn` features are added by the "default" feature ("quote" is -added by "printing" and "proc-macro", both of which are default features). -+ -If you're having difficulty cross-referencing the de-duplicated `(*)` entries, -try with the `--no-dedupe` flag to get the full output. + If you're having difficulty cross-referencing the de-duplicated `(*)` + entries, try with the `--no-dedupe` flag to get the full output. -== SEE ALSO -man:cargo[1], man:cargo-metadata[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-metadata" 1}} diff --git a/src/doc/man/cargo-uninstall.md b/src/doc/man/cargo-uninstall.md index b75a10401e2..73c50c7a1de 100644 --- a/src/doc/man/cargo-uninstall.md +++ b/src/doc/man/cargo-uninstall.md @@ -1,57 +1,63 @@ -= cargo-uninstall(1) -:idprefix: cargo_uninstall_ -:doctype: manpage +# cargo-uninstall(1) -== NAME +## NAME cargo-uninstall - Remove a Rust binary -== SYNOPSIS +## SYNOPSIS -`cargo uninstall [_OPTIONS_] [_SPEC_...]` +`cargo uninstall` [_options_] [_spec_...] -== DESCRIPTION +## DESCRIPTION -This command removes a package installed with man:cargo-install[1]. The _SPEC_ +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]). +{{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[] +{{> description-install-root }} -== OPTIONS +## OPTIONS -=== Install Options +### Install Options -*-p*:: -*--package* _SPEC_...:: - Package to uninstall. +{{#options}} -*--bin* _NAME_...:: - Only uninstall the binary _NAME_. +{{#option "`-p`" "`--package` _spec_..." }} +Package to uninstall. +{{/option}} -*--root* _DIR_:: - Directory to uninstall packages from. +{{#option "`--bin` _name_..." }} +Only uninstall the binary _name_. +{{/option}} -=== Display Options +{{#option "`--root` _dir_" }} +Directory to uninstall packages from. +{{/option}} -include::options-display.adoc[] +{{/options}} -=== Common Options +### Display Options -include::options-common.adoc[] +{{#options}} -include::section-environment.adoc[] +{{> options-display }} -include::section-exit-status.adoc[] +{{/options}} -== EXAMPLES +{{> section-options-common }} -. Uninstall a previously installed package. +{{> section-environment }} - cargo uninstall ripgrep +{{> section-exit-status }} -== SEE ALSO -man:cargo[1], man:cargo-install[1] +## EXAMPLES + +1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-install" 1}} diff --git a/src/doc/man/cargo-update.md b/src/doc/man/cargo-update.md index c8a5274350a..db0210b8bfe 100644 --- a/src/doc/man/cargo-update.md +++ b/src/doc/man/cargo-update.md @@ -1,81 +1,90 @@ -= cargo-update(1) -:idprefix: cargo_update_ -:doctype: manpage +# cargo-update(1) -== NAME +## NAME cargo-update - Update dependencies as recorded in the local lock file -== SYNOPSIS +## SYNOPSIS -`cargo update [_OPTIONS_]` +`cargo update` [_options_] -== DESCRIPTION +## 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]. +by commands such as {{man "cargo-build" 1}} or {{man "cargo-generate-lockfile" 1}}. -== OPTIONS +## OPTIONS -=== Update Options +### Update Options + +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Update only the specified packages. This flag may be specified +multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format. -*-p* _SPEC_...:: -*--package* _SPEC_...:: - Update only the specified packages. This flag may be specified - multiple times. See man:cargo-pkgid[1] for the SPEC format. -+ If packages are specified with the `-p` flag, then a conservative update of the lockfile will be performed. This means that only the dependency specified by SPEC will be updated. Its transitive dependencies will be updated only if SPEC cannot be updated without updating dependencies. All other dependencies will remain locked at their currently recorded versions. -+ + If `-p` is not specified, all dependencies are updated. +{{/option}} + +{{#option "`--aggressive`" }} +When used with `-p`, dependencies of _spec_ are forced to update as well. +Cannot be used with `--precise`. +{{/option}} + +{{#option "`--precise` _precise_" }} +When used with `-p`, allows you to specify a specific version number to set +the package to. If the package comes from a git repository, this can be a git +revision (such as a SHA hash or tag). +{{/option}} -*--aggressive*:: - When used with `-p`, dependencies of _SPEC_ are forced to update as well. - Cannot be used with `--precise`. +{{#option "`--dry-run`" }} +Displays what would be updated, but doesn't actually write the lockfile. +{{/option}} -*--precise* _PRECISE_:: - When used with `-p`, allows you to specify a specific version number to - set the package to. If the package comes from a git repository, this can - be a git revision (such as a SHA hash or tag). +{{/options}} -*--dry-run*:: - Displays what would be updated, but doesn't actually write the lockfile. +### Display Options -=== Display Options +{{#options}} +{{> options-display }} +{{/options}} -include::options-display.adoc[] +### Manifest Options -=== Manifest Options +{{#options}} -include::options-manifest-path.adoc[] +{{> options-manifest-path }} -include::options-locked.adoc[] +{{> options-locked }} -=== Common Options +{{/options}} -include::options-common.adoc[] +{{> section-options-common }} -include::section-environment.adoc[] +{{> section-environment }} -include::section-exit-status.adoc[] +{{> section-exit-status }} -== EXAMPLES +## EXAMPLES -. Update all dependencies in the lockfile: +1. Update all dependencies in the lockfile: - cargo update + cargo update -. Update only specific dependencies: +2. Update only specific dependencies: - cargo update -p foo -p bar + cargo update -p foo -p bar -. Set a specific dependency to a specific version: +3. Set a specific dependency to a specific version: - cargo update -p foo --precise 1.2.3 + cargo update -p foo --precise 1.2.3 -== SEE ALSO -man:cargo[1], man:cargo-generate-lockfile[1] +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}} diff --git a/src/doc/man/cargo-vendor.md b/src/doc/man/cargo-vendor.md index d1d3fc3bb87..f7c4532035c 100644 --- a/src/doc/man/cargo-vendor.md +++ b/src/doc/man/cargo-vendor.md @@ -1,16 +1,14 @@ -= cargo-vendor(1) -:idprefix: cargo_vendor_ -:doctype: manpage +# cargo-vendor(1) -== NAME +## NAME cargo-vendor - Vendor all dependencies locally -== SYNOPSIS +## SYNOPSIS -`cargo vendor [_OPTIONS_] [_PATH_]` +`cargo vendor` [_options_] [_path_] -== DESCRIPTION +## DESCRIPTION This cargo subcommand will vendor all crates.io and git dependencies for a project into the specified directory at ``. After this command completes @@ -21,62 +19,75 @@ specified with the `-s` option. The `cargo vendor` command will also print out the configuration necessary to use the vendored sources, which you will need to add to `.cargo/config.toml`. -== OPTIONS +## OPTIONS -=== Vendor Options +### Vendor Options -*-s* _MANIFEST_:: -*--sync* _MANIFEST_:: - Specify extra `Cargo.toml` manifests to workspaces which should also be - vendored and synced to the output. +{{#options}} -*--no-delete*:: - Don't delete the "vendor" directory when vendoring, but rather keep all - existing contents of the vendor directory +{{#option "`-s` _manifest_" "`--sync` _manifest_" }} +Specify extra `Cargo.toml` manifests to workspaces which should also be +vendored and synced to the output. +{{/option}} -*--respect-source-config*:: - Instead of ignoring `[source]` configuration by default in `.cargo/config.toml` - read it and use it when downloading crates from crates.io, for example +{{#option "`--no-delete`" }} +Don't delete the "vendor" directory when vendoring, but rather keep all +existing contents of the vendor directory +{{/option}} -*--versioned-dirs*:: - Normally versions are only added to disambiguate multiple versions of the - same package. This option causes all directories in the "vendor" directory - to be versioned, which makes it easier to track the history of vendored - packages over time, and can help with the performance of re-vendoring when - only a subset of the packages have changed. +{{#option "`--respect-source-config`" }} +Instead of ignoring `[source]` configuration by default in `.cargo/config.toml` +read it and use it when downloading crates from crates.io, for example +{{/option}} -=== Manifest Options +{{#option "`--versioned-dirs`" }} +Normally versions are only added to disambiguate multiple versions of the +same package. This option causes all directories in the "vendor" directory +to be versioned, which makes it easier to track the history of vendored +packages over time, and can help with the performance of re-vendoring when +only a subset of the packages have changed. +{{/option}} -include::options-manifest-path.adoc[] +{{/options}} -=== Display Options +### Manifest Options -include::options-display.adoc[] +{{#options}} -=== Common Options +{{> options-manifest-path }} -include::options-common.adoc[] +{{> options-locked }} -include::options-locked.adoc[] +{{/options}} -include::section-environment.adoc[] +### Display Options -include::section-exit-status.adoc[] +{{#options}} -== EXAMPLES +{{> options-display }} -. Vendor all dependencies into a local "vendor" folder +{{/options}} - cargo vendor +{{> section-options-common }} -. Vendor all dependencies into a local "third-party/vendor" folder +{{> section-environment }} - cargo vendor third-party/vendor +{{> section-exit-status }} -. Vendor the current workspace as well as another to "vendor" +## EXAMPLES - cargo vendor -s ../path/to/Cargo.toml +1. Vendor all dependencies into a local "vendor" folder -== SEE ALSO -man:cargo[1] + cargo vendor + +2. Vendor all dependencies into a local "third-party/vendor" folder + + cargo vendor third-party/vendor + +3. Vendor the current workspace as well as another to "vendor" + + cargo vendor -s ../path/to/Cargo.toml + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-verify-project.md b/src/doc/man/cargo-verify-project.md index 7b963f8c5dd..99b749087b7 100644 --- a/src/doc/man/cargo-verify-project.md +++ b/src/doc/man/cargo-verify-project.md @@ -1,16 +1,14 @@ -= cargo-verify-project(1) -:idprefix: cargo_verify-project_ -:doctype: manpage +# cargo-verify-project(1) -== NAME +## NAME cargo-verify-project - Check correctness of crate manifest -== SYNOPSIS +## SYNOPSIS -`cargo verify-project [_OPTIONS_]` +`cargo verify-project` [_options_] -== DESCRIPTION +## 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: @@ -21,37 +19,40 @@ An invalid workspace will display: {"invalid":"human-readable error message"} -== OPTIONS +## OPTIONS -=== Display Options +### Display Options -include::options-display.adoc[] +{{#options}} -=== Manifest Options +{{> options-display }} -include::options-manifest-path.adoc[] +{{/options}} -include::options-locked.adoc[] +### Manifest Options -=== Common Options +{{#options}} -include::options-common.adoc[] +{{> options-manifest-path }} -include::section-environment.adoc[] +{{> options-locked }} -== Exit Status +{{/options}} -0:: - The workspace is OK. +{{> section-options-common }} -1:: - The workspace is invalid. +{{> section-environment }} -== EXAMPLES +## EXIT STATUS -. Check the current workspace for errors: +* `0`: The workspace is OK. +* `1`: The workspace is invalid. - cargo verify-project +## EXAMPLES -== SEE ALSO -man:cargo[1], man:cargo-package[1] +1. Check the current workspace for errors: + + cargo verify-project + +## SEE ALSO +{{man "cargo" 1}}, {{man "cargo-package" 1}} diff --git a/src/doc/man/cargo-version.md b/src/doc/man/cargo-version.md index 4c3bb7a1be3..c6e4535323d 100644 --- a/src/doc/man/cargo-version.md +++ b/src/doc/man/cargo-version.md @@ -1,39 +1,41 @@ -= cargo-version(1) -:idprefix: cargo_version_ -:doctype: manpage +# cargo-version(1) -== NAME +## NAME cargo-version - Show version information -== SYNOPSIS +## SYNOPSIS -`cargo version [_OPTIONS_]` +`cargo version` [_options_] -== DESCRIPTION +## DESCRIPTION Displays the version of Cargo. -== OPTIONS +## OPTIONS -*-v*:: -*--verbose*:: - Display additional version information. +{{#options}} -== EXAMPLES +{{#option "`-v`" "`--verbose`" }} +Display additional version information. +{{/option}} -. Display the version: +{{/options}} - cargo version +## EXAMPLES -. The version is also available via flags: +1. Display the version: - cargo --version - cargo -V + cargo version -. Display extra version information: +2. The version is also available via flags: - cargo -Vv + cargo --version + cargo -V -== SEE ALSO -man:cargo[1] +3. Display extra version information: + + cargo -Vv + +## SEE ALSO +{{man "cargo" 1}} diff --git a/src/doc/man/cargo-yank.md b/src/doc/man/cargo-yank.md index a08c71777a0..0a3ba396585 100644 --- a/src/doc/man/cargo-yank.md +++ b/src/doc/man/cargo-yank.md @@ -1,16 +1,14 @@ -= cargo-yank(1) -:idprefix: cargo_yank_ -:doctype: manpage +# cargo-yank(1) -== NAME +## NAME cargo-yank - Remove a pushed crate from the index -== SYNOPSIS +## SYNOPSIS -`cargo yank [_OPTIONS_] --vers _VERSION_ [_CRATE_]` +`cargo yank` [_options_] `--vers` _version_ [_crate_] -== DESCRIPTION +## 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 @@ -21,44 +19,52 @@ 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]. +or using {{man "cargo-login" 1}}. If the crate name is not specified, it will use the package name from the current directory. -== OPTIONS +## OPTIONS -=== Yank Options +### Yank Options -*--vers* _VERSION_:: - The version to yank or un-yank. +{{#options}} -*--undo*:: - Undo a yank, putting a version back into the index. +{{#option "`--vers` _version_" }} +The version to yank or un-yank. +{{/option}} -include::options-token.adoc[] +{{#option "`--undo`" }} +Undo a yank, putting a version back into the index. +{{/option}} -include::options-index.adoc[] +{{> options-token }} -include::options-registry.adoc[] +{{> options-index }} -=== Display Options +{{> options-registry }} -include::options-display.adoc[] +{{/options}} -=== Common Options +### Display Options -include::options-common.adoc[] +{{#options}} -include::section-environment.adoc[] +{{> options-display }} -include::section-exit-status.adoc[] +{{/options}} -== EXAMPLES +{{> section-options-common }} -. Yank a crate from the index: +{{> section-environment }} - cargo yank --vers 1.0.7 foo +{{> section-exit-status }} -== SEE ALSO -man:cargo[1], man:cargo-login[1], man:cargo-publish[1] +## EXAMPLES + +1. 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.md b/src/doc/man/cargo.md index 59c7b1fccc9..901e1db02bc 100644 --- a/src/doc/man/cargo.md +++ b/src/doc/man/cargo.md @@ -1,226 +1,233 @@ -= cargo(1) -:doctype: manpage +# cargo(1) -== NAME +## NAME cargo - The Rust package manager -== SYNOPSIS +## SYNOPSIS -[%hardbreaks] -`cargo [_OPTIONS_] _COMMAND_ [_ARGS_]` -`cargo [_OPTIONS_] --version` -`cargo [_OPTIONS_] --list` -`cargo [_OPTIONS_] --help` -`cargo [_OPTIONS_] --explain _CODE_` +`cargo` [_options_] _command_ [_args_]\ +`cargo` [_options_] `--version`\ +`cargo` [_options_] `--list`\ +`cargo` [_options_] `--help`\ +`cargo` [_options_] `--explain` _code_ -== DESCRIPTION +## DESCRIPTION This program is a package manager and build tool for the Rust language, available at . -== COMMANDS +## COMMANDS -=== Build Commands +### Build Commands -man:cargo-bench[1]:: - Execute benchmarks of a package. +{{man "cargo-bench" 1}}\ +    Execute benchmarks of a package. -man:cargo-build[1]:: - Compile 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-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-clean" 1}}\ +    Remove artifacts that Cargo has generated in the past. -man:cargo-doc[1]:: - Build a package's documentation. +{{man "cargo-doc" 1}}\ +    Build a package's documentation. -man:cargo-fetch[1]:: - Fetch dependencies of a package from the network. +{{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-fix" 1}}\ +    Automatically fix lint warnings reported by rustc. -man:cargo-run[1]:: - Run a binary or example of the local package. +{{man "cargo-run" 1}}\ +    Run a binary or example of the local package. -man:cargo-rustc[1]:: - Compile a package, and pass extra options to the compiler. +{{man "cargo-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-rustdoc" 1}}\ +    Build a package's documentation, using specified custom flags. -man:cargo-test[1]:: - Execute unit and integration tests of a package. +{{man "cargo-test" 1}}\ +    Execute unit and integration tests of a package. -=== Manifest Commands +### Manifest Commands -man:cargo-generate-lockfile[1]:: - Generate `Cargo.lock` for a project. +{{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-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-metadata" 1}}\ +    Output the resolved dependencies of a package in machine-readable format. -man:cargo-pkgid[1]:: - Print a fully qualified package specification. +{{man "cargo-pkgid" 1}}\ +    Print a fully qualified package specification. -man:cargo-tree[1]:: - Display a tree visualization of a dependency graph. +{{man "cargo-tree" 1}}\ +    Display a tree visualization of a dependency graph. -man:cargo-update[1]:: - Update dependencies as recorded in the local lock file. +{{man "cargo-update" 1}}\ +    Update dependencies as recorded in the local lock file. -man:cargo-vendor[1]:: - Vendor all dependencies locally. +{{man "cargo-vendor" 1}}\ +    Vendor all dependencies locally. -man:cargo-verify-project[1]:: - Check correctness of crate manifest. +{{man "cargo-verify-project" 1}}\ +    Check correctness of crate manifest. -=== Package Commands +### Package Commands -man:cargo-init[1]:: - Create a new Cargo package in an existing directory. +{{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-install" 1}}\ +    Build and install a Rust binary. -man:cargo-new[1]:: - Create a new Cargo package. +{{man "cargo-new" 1}}\ +    Create a new Cargo package. -man:cargo-search[1]:: - Search packages in crates.io. +{{man "cargo-search" 1}}\ +    Search packages in crates.io. -man:cargo-uninstall[1]:: - Remove a Rust binary. +{{man "cargo-uninstall" 1}}\ +    Remove a Rust binary. -=== Publishing Commands +### Publishing Commands -man:cargo-login[1]:: - Save an API token from the registry locally. +{{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-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-package" 1}}\ +    Assemble the local package into a distributable tarball. -man:cargo-publish[1]:: - Upload a package to the registry. +{{man "cargo-publish" 1}}\ +    Upload a package to the registry. -man:cargo-yank[1]:: - Remove a pushed crate from the index. +{{man "cargo-yank" 1}}\ +    Remove a pushed crate from the index. -=== General Commands +### General Commands -man:cargo-help[1]:: - Display help information about Cargo. +{{man "cargo-help" 1}}\ +    Display help information about Cargo. -man:cargo-version[1]:: - Show version information. +{{man "cargo-version" 1}}\ +    Show version information. -== OPTIONS +## OPTIONS -=== Special Options +### Special Options -*-V*:: -*--version*:: - Print version info and exit. If used with `--verbose`, prints extra - information. +{{#options}} -*--list*:: - List all installed Cargo subcommands. If used with `--verbose`, prints - extra information. +{{#option "`-V`" "`--version`" }} +Print version info and exit. If used with `--verbose`, prints extra +information. +{{/option}} -*--explain _CODE_*:: - Run `rustc --explain CODE` which will print out a detailed explanation of - an error message (for example, `E0004`). +{{#option "`--list`" }} +List all installed Cargo subcommands. If used with `--verbose`, prints extra +information. +{{/option}} -=== Display Options +{{#option "`--explain` _code_" }} +Run `rustc --explain CODE` which will print out a detailed explanation of an +error message (for example, `E0004`). +{{/option}} -include::options-display.adoc[] +{{/options}} -=== Manifest Options +### Display Options -include::options-locked.adoc[] +{{#options}} -=== Common Options +{{> options-display }} -include::options-common.adoc[] +{{/options}} -include::section-environment.adoc[] +### Manifest Options -include::section-exit-status.adoc[] +{{#options}} +{{> options-locked }} +{{/options}} -== FILES +{{> section-options-common }} -`~/.cargo/`:: - Default location for Cargo's "home" directory where it stores various - files. The location can be changed with the `CARGO_HOME` environment - variable. +{{> section-environment }} -`$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. +{{> section-exit-status }} -`$CARGO_HOME/config.toml`:: - The global configuration file. See linkcargo:reference/config.html[the reference] - for more information about configuration files. +## FILES -`.cargo/config.toml`:: - Cargo automatically searches for a file named `.cargo/config.toml` in the - current directory, and all parent directories. These configuration files - will be merged with the global configuration file. +`~/.cargo/`\ +    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/credentials.toml`:: - Private authentication information for logging in to a registry. +`$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/registry/`:: - This directory contains cached downloads of the registry index and any - downloaded dependencies. +`$CARGO_HOME/config.toml`\ +    The global configuration file. See [the reference](../reference/config.html) +for more information about configuration files. -`$CARGO_HOME/git/`:: - This directory contains cached downloads of git dependencies. +`.cargo/config.toml`\ +    Cargo automatically searches for a file named `.cargo/config.toml` in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file. + +`$CARGO_HOME/credentials.toml`\ +    Private authentication information for logging in to a registry. + +`$CARGO_HOME/registry/`\ +    This directory contains cached downloads of the registry index and any +downloaded dependencies. + +`$CARGO_HOME/git/`\ +    This directory contains cached downloads of git dependencies. Please note that the internal structure of the `$CARGO_HOME` directory is not stable yet and may be subject to change. -== EXAMPLES +## EXAMPLES -. Build a local package and all of its dependencies: +1. Build a local package and all of its dependencies: - cargo build + cargo build -. Build a package with optimizations: +2. Build a package with optimizations: - cargo build --release + cargo build --release -. Run tests for a cross-compiled target: +3. Run tests for a cross-compiled target: - cargo test --target i686-unknown-linux-gnu + cargo test --target i686-unknown-linux-gnu -. Create a new package that builds an executable: +4. Create a new package that builds an executable: - cargo new foobar + cargo new foobar -. Create a package in the current directory: +5. Create a package in the current directory: - mkdir foo && cd foo - cargo init . + mkdir foo && cd foo + cargo init . -. Learn about a command's options and usage: +6. Learn about a command's options and usage: - cargo help clean + cargo help clean -== BUGS +## BUGS -See https://github.com/rust-lang/cargo/issues for issues. +See for issues. -== SEE ALSO -man:rustc[1], man:rustdoc[1] +## SEE ALSO +{{man "rustc" 1}}, {{man "rustdoc" 1}} diff --git a/src/doc/man/includes/description-install-root.md b/src/doc/man/includes/description-install-root.md index d7773d3b20a..50cf51baecf 100644 --- a/src/doc/man/includes/description-install-root.md +++ b/src/doc/man/includes/description-install-root.md @@ -2,6 +2,6 @@ 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] +- `install.root` Cargo [config value](../reference/config.html) - `CARGO_HOME` environment variable - `$HOME/.cargo` diff --git a/src/doc/man/includes/description-new-authors.md b/src/doc/man/includes/description-new-authors.md index 0435295b726..c3380cbf1a0 100644 --- a/src/doc/man/includes/description-new-authors.md +++ b/src/doc/man/includes/description-new-authors.md @@ -20,5 +20,5 @@ The email address is optional and is determined from: - `user.email` git configuration value - `EMAIL` environment variable -See linkcargo:reference/config.html[the reference] for more information about +See [the reference](../reference/config.html) for more information about configuration files. diff --git a/src/doc/man/includes/options-display.md b/src/doc/man/includes/options-display.md index cc2e2263398..b744de82068 100644 --- a/src/doc/man/includes/options-display.md +++ b/src/doc/man/includes/options-display.md @@ -1,22 +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]. +{{#option "`-v`" "`--verbose`"}} +Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the `term.verbose` +[config value](../reference/config.html). +{{/option}} -*-q*:: -*--quiet*:: - No output printed to stdout. +{{#option "`-q`" "`--quiet`"}} +No output printed to stdout. +{{/option}} + +{{#option "`--color` _when_"}} +Control when colored output is used. Valid values: -*--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]. +[config value](../reference/config.html). +{{/option}} diff --git a/src/doc/man/includes/options-index.md b/src/doc/man/includes/options-index.md index 1321866bae7..b19b9836511 100644 --- a/src/doc/man/includes/options-index.md +++ b/src/doc/man/includes/options-index.md @@ -1,2 +1,3 @@ -*--index* _INDEX_:: - The URL of the registry index to use. +{{#option "`--index` _index_"}} +The URL of the registry index to use. +{{/option}} diff --git a/src/doc/man/includes/options-jobs.md b/src/doc/man/includes/options-jobs.md index 9d817426ba1..7dc00e3de83 100644 --- a/src/doc/man/includes/options-jobs.md +++ b/src/doc/man/includes/options-jobs.md @@ -1,5 +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. +{{#option "`-j` _N_" "`--jobs` _N_"}} +Number of parallel jobs to run. May also be specified with the +`build.jobs` [config value](../reference/config.html). Defaults to +the number of CPUs. +{{/option}} diff --git a/src/doc/man/includes/options-locked.md b/src/doc/man/includes/options-locked.md index 45bbfa5117d..c9ac9524e3c 100644 --- a/src/doc/man/includes/options-locked.md +++ b/src/doc/man/includes/options-locked.md @@ -1,24 +1,25 @@ -*--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. -+ +{{#option "`--frozen`" "`--locked`"}} +Either of these flags requires that the `Cargo.lock` file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The `--frozen` flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date. + These may be used in environments where you want to assert that the `Cargo.lock` file is up-to-date (such as a CI build) or want to avoid network access. +{{/option}} + +{{#option "`--offline`"}} +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. -*--offline*:: - Prevents Cargo from accessing the network for any reason. Without this - flag, Cargo will stop with an error if it needs to access the network and - the network is not available. With this flag, Cargo will attempt to - proceed without the network if possible. -+ Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the man:cargo-fetch[1] command to download dependencies before going +See the {{man "cargo-fetch" 1}} command to download dependencies before going offline. -+ -May also be specified with the `net.offline` linkcargo:reference/config.html[config value]. + +May also be specified with the `net.offline` [config value](../reference/config.html). +{{/option}} diff --git a/src/doc/man/includes/options-manifest-path.md b/src/doc/man/includes/options-manifest-path.md index 79a2394a688..b1d6eab76ee 100644 --- a/src/doc/man/includes/options-manifest-path.md +++ b/src/doc/man/includes/options-manifest-path.md @@ -1,3 +1,4 @@ -*--manifest-path* _PATH_:: - Path to the `Cargo.toml` file. By default, Cargo searches for the - `Cargo.toml` file in the current directory or any parent directory. +{{#option "`--manifest-path` _path_" }} +Path to the `Cargo.toml` file. By default, Cargo searches for the +`Cargo.toml` file in the current directory or any parent directory. +{{/option}} diff --git a/src/doc/man/includes/options-message-format.md b/src/doc/man/includes/options-message-format.md index 818d78f8127..9815b5b1e0b 100644 --- a/src/doc/man/includes/options-message-format.md +++ b/src/doc/man/includes/options-message-format.md @@ -1,11 +1,11 @@ -*--message-format* _FMT_:: - The output format for diagnostic messages. Can be specified multiple times - and consists of comma-separated values. Valid values: -+ +{{#option "`--message-format` _fmt_" }} +The output format for diagnostic messages. Can be specified multiple times +and consists of comma-separated values. Valid values: + - `human` (default): Display in a human-readable text format. - `short`: Emit shorter, human-readable text messages. - `json`: Emit JSON messages to stdout. See - linkcargo:reference/external-tools.html#json-messages[the reference] + [the reference](../reference/external-tools.html#json-messages) for more details. - `json-diagnostic-short`: Ensure the `rendered` field of JSON messages contains the "short" rendering from rustc. @@ -16,3 +16,4 @@ in JSON messages printed, but instead Cargo itself should render the JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. +{{/option}} diff --git a/src/doc/man/includes/options-new.md b/src/doc/man/includes/options-new.md index 2218599ae2a..2b62729d65f 100644 --- a/src/doc/man/includes/options-new.md +++ b/src/doc/man/includes/options-new.md @@ -1,29 +1,39 @@ -*--bin*:: - Create a package with a binary target (`src/main.rs`). - This is the default behavior. - -*--lib*:: - Create a package with a library target (`src/lib.rs`). - -*--edition* _EDITION_:: - Specify the Rust edition to use. Default is 2018. - Possible values: 2015, 2018 - -*--name* _NAME_:: - Set the package name. Defaults to the directory name. - -*--vcs* _VCS_:: - Initialize a new VCS repository for the given version control system (git, - hg, pijul, or fossil) or do not initialize any version control at all - (none). If not specified, defaults to `git` or the configuration value - `cargo-new.vcs`, or `none` if already inside a VCS repository. - -*--registry* _REGISTRY_:: - This sets the `publish` field in `Cargo.toml` to the given registry name - which will restrict publishing only to that registry. -+ -Registry names are defined in linkcargo:reference/config.html[Cargo config files]. +{{#options}} + +{{#option "`--bin`" }} +Create a package with a binary target (`src/main.rs`). +This is the default behavior. +{{/option}} + +{{#option "`--lib`" }} +Create a package with a library target (`src/lib.rs`). +{{/option}} + +{{#option "`--edition` _edition_" }} +Specify the Rust edition to use. Default is 2018. +Possible values: 2015, 2018 +{{/option}} + +{{#option "`--name` _name_" }} +Set the package name. Defaults to the directory name. +{{/option}} + +{{#option "`--vcs` _vcs_" }} +Initialize a new VCS repository for the given version control system (git, +hg, pijul, or fossil) or do not initialize any version control at all +(none). If not specified, defaults to `git` or the configuration value +`cargo-new.vcs`, or `none` if already inside a VCS repository. +{{/option}} + +{{#option "`--registry` _registry_" }} +This sets the `publish` field in `Cargo.toml` to the given registry name +which will restrict publishing only to that registry. + +Registry names are defined in [Cargo config files](../reference/config.html). If not specified, the default registry defined by the `registry.default` config key is used. If the default registry is not set and `--registry` is not used, the `publish` field will not be set which means that publishing will not be restricted. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-profile.md b/src/doc/man/includes/options-profile.md index 3c5ad14c764..275bbef7bb2 100644 --- a/src/doc/man/includes/options-profile.md +++ b/src/doc/man/includes/options-profile.md @@ -1,6 +1,7 @@ -*--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. +{{#option "`--profile` _name_" }} +Changes {{lower actionverb}} behavior. Currently only `test` is supported, +which will {{lower actionverb}} with the `#[cfg(test)]` attribute enabled. +This is useful to have it {{lower actionverb}} unit tests which are usually +excluded via the `cfg` attribute. This does not change the actual profile +used. +{{/option}} diff --git a/src/doc/man/includes/options-registry.md b/src/doc/man/includes/options-registry.md index a0c4c27c8e8..23e1706894c 100644 --- a/src/doc/man/includes/options-registry.md +++ b/src/doc/man/includes/options-registry.md @@ -1,4 +1,6 @@ -*--registry* _REGISTRY_:: - Name of the registry to use. Registry names are defined in linkcargo:reference/config.html[Cargo config files]. - If not specified, the default registry is used, which is defined by the - `registry.default` config key which defaults to `crates-io`. +{{#option "`--registry` _registry_"}} +Name of the registry to use. Registry names are defined in [Cargo config +files](../reference/config.html). If not specified, the default registry is used, +which is defined by the `registry.default` config key which defaults to +`crates-io`. +{{/option}} diff --git a/src/doc/man/includes/options-release.md b/src/doc/man/includes/options-release.md index e99539172a3..4ee0fe6d628 100644 --- a/src/doc/man/includes/options-release.md +++ b/src/doc/man/includes/options-release.md @@ -1,3 +1,5 @@ -*--release*:: - {actionverb} optimized artifacts with the `release` profile. See the - <> section for details on how this affects profile selection. +{{#option "`--release`"}} +{{actionverb}} optimized artifacts with the `release` profile. See the +[PROFILES](#profiles) section for details on how this affects profile +selection. +{{/option}} diff --git a/src/doc/man/includes/options-target-dir.md b/src/doc/man/includes/options-target-dir.md index f044bd71223..009790425cc 100644 --- a/src/doc/man/includes/options-target-dir.md +++ b/src/doc/man/includes/options-target-dir.md @@ -1,5 +1,6 @@ -*--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. +{{#option "`--target-dir` _directory_"}} +Directory for all generated artifacts and intermediate files. May also be +specified with the `CARGO_TARGET_DIR` environment variable, or the +`build.target-dir` [config value](../reference/config.html). Defaults +to `target` in the root of the workspace. +{{/option}} diff --git a/src/doc/man/includes/options-target-triple.md b/src/doc/man/includes/options-target-triple.md index 9cb6d7c85e5..6ad03c6f4be 100644 --- a/src/doc/man/includes/options-target-triple.md +++ b/src/doc/man/includes/options-target-triple.md @@ -1,12 +1,13 @@ -*--target* _TRIPLE_:: - {actionverb} for the given architecture. The default is the host - architecture. The general format of the triple is - `---`. Run `rustc --print target-list` for a - list of supported targets. -+ +{{#option "`--target` _triple_"}} +{{actionverb}} for the given architecture. The default is the host +architecture. The general format of the triple is +`---`. Run `rustc --print target-list` for a +list of supported targets. + This may also be specified with the `build.target` -linkcargo:reference/config.html[config value]. -+ +[config value](../reference/config.html). + Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -linkcargo:guide/build-cache.html[build cache] documentation for more details. +[build cache](../guide/build-cache.html) documentation for more details. +{{/option}} diff --git a/src/doc/man/includes/options-targets-lib-bin.md b/src/doc/man/includes/options-targets-lib-bin.md index 8668ba84ba9..60721ebf24e 100644 --- a/src/doc/man/includes/options-targets-lib-bin.md +++ b/src/doc/man/includes/options-targets-lib-bin.md @@ -1,8 +1,11 @@ -*--lib*:: - {actionverb} the package's library. +{{#option "`--lib`" }} +{{actionverb}} the package's library. +{{/option}} -*--bin* _NAME_...:: - {actionverb} the specified binary. This flag may be specified multiple times. +{{#option "`--bin` _name_..." }} +{{actionverb}} the specified binary. This flag may be specified multiple times. +{{/option}} -*--bins*:: - {actionverb} all binary targets. +{{#option "`--bins`" }} +{{actionverb}} all binary targets. +{{/option}} diff --git a/src/doc/man/includes/options-targets.md b/src/doc/man/includes/options-targets.md index 6a8a46cd714..da8dba2c8dc 100644 --- a/src/doc/man/includes/options-targets.md +++ b/src/doc/man/includes/options-targets.md @@ -1,39 +1,50 @@ -Passing target selection flags will convert:lowercase[{actionverb}] only the -specified targets. - -include::options-targets-lib-bin.adoc[] - -*--example* _NAME_...:: - {actionverb} the specified example. This flag may be specified multiple times. - -*--examples*:: - {actionverb} all example targets. - -*--test* _NAME_...:: - {actionverb} the specified integration test. This flag may be specified multiple - times. - -*--tests*:: - {actionverb} all targets in test mode that have the `test = true` manifest - flag set. By default this includes the library and binaries built as - unittests, and integration tests. Be aware that this will also build any - required dependencies, so the lib target may be built twice (once as a - unittest, and once as a dependency for binaries, integration tests, etc.). - Targets may be enabled or disabled by setting the `test` flag in the - manifest settings for the target. - -*--bench* _NAME_...:: - {actionverb} the specified benchmark. This flag may be specified multiple times. - -*--benches*:: - {actionverb} all targets in benchmark mode that have the `bench = true` - manifest flag set. By default this includes the library and binaries built - as benchmarks, and bench targets. Be aware that this will also build any - required dependencies, so the lib target may be built twice (once as a - benchmark, and once as a dependency for binaries, benchmarks, etc.). - Targets may be enabled or disabled by setting the `bench` flag in the - manifest settings for the target. - -*--all-targets*:: - {actionverb} all targets. This is equivalent to specifying `--lib --bins - --tests --benches --examples`. +Passing target selection flags will {{lower actionverb}} only the specified +targets. + +{{#options}} + +{{> options-targets-lib-bin }} + +{{#option "`--example` _name_..." }} +{{actionverb}} the specified example. This flag may be specified multiple times. +{{/option}} + +{{#option "`--examples`" }} +{{actionverb}} all example targets. +{{/option}} + +{{#option "`--test` _name_..." }} +{{actionverb}} the specified integration test. This flag may be specified +multiple times. +{{/option}} + +{{#option "`--tests`" }} +{{actionverb}} all targets in test mode that have the `test = true` manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the `test` flag in the +manifest settings for the target. +{{/option}} + +{{#option "`--bench` _name_..." }} +{{actionverb}} the specified benchmark. This flag may be specified multiple times. +{{/option}} + +{{#option "`--benches`" }} +{{actionverb}} all targets in benchmark mode that have the `bench = true` +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the `bench` flag in the +manifest settings for the target. +{{/option}} + +{{#option "`--all-targets`" }} +{{actionverb}} all targets. This is equivalent to specifying `--lib --bins +--tests --benches --examples`. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-test.md b/src/doc/man/includes/options-test.md index 0cdcb3d7efc..1d2447e8d3f 100644 --- a/src/doc/man/includes/options-test.md +++ b/src/doc/man/includes/options-test.md @@ -1,8 +1,14 @@ -*--no-run*:: - Compile, but don't run {nouns}. +{{#options}} -*--no-fail-fast*:: - Run all {nouns} regardless of failure. Without this flag, Cargo will exit - after the first executable fails. The Rust test harness will run all - {nouns} within the executable to completion, this flag only applies to - the executable as a whole. +{{#option "`--no-run`" }} +Compile, but don't run {{nouns}}. +{{/option}} + +{{#option "`--no-fail-fast`" }} +Run all {{nouns}} regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all {{nouns}} +within the executable to completion, this flag only applies to the executable +as a whole. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/options-token.md b/src/doc/man/includes/options-token.md index 5f25ffbf243..855204de2ab 100644 --- a/src/doc/man/includes/options-token.md +++ b/src/doc/man/includes/options-token.md @@ -1,10 +1,11 @@ -*--token* _TOKEN_:: - API token to use when authenticating. This overrides the token stored in - the credentials file (which is created by man:cargo-login[1]). -+ -linkcargo:reference/config.html[Cargo config] environment variables can be +{{#option "`--token` _token_" }} +API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by {{man "cargo-login" 1}}). + +[Cargo config](../reference/config.html) environment variables can be used to override the tokens stored in the credentials file. The token for crates.io may be specified with the `CARGO_REGISTRY_TOKEN` environment variable. Tokens for other registries may be specified with environment variables of the form `CARGO_REGISTRIES_NAME_TOKEN` where `NAME` is the name of the registry in all capital letters. +{{/option}} diff --git a/src/doc/man/includes/section-environment.md b/src/doc/man/includes/section-environment.md index 5cc69e995a0..aae5f078a83 100644 --- a/src/doc/man/includes/section-environment.md +++ b/src/doc/man/includes/section-environment.md @@ -1,4 +1,4 @@ -== ENVIRONMENT +## ENVIRONMENT -See linkcargo:reference/environment-variables.html[the reference] for +See [the reference](../reference/environment-variables.html) for details on environment variables that Cargo reads. diff --git a/src/doc/man/includes/section-exit-status.md b/src/doc/man/includes/section-exit-status.md index 427b3903c19..a8123366d69 100644 --- a/src/doc/man/includes/section-exit-status.md +++ b/src/doc/man/includes/section-exit-status.md @@ -1,7 +1,4 @@ -== Exit Status +## EXIT STATUS -0:: - Cargo succeeded. - -101:: - Cargo failed to complete. +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. diff --git a/src/doc/man/includes/section-features.md b/src/doc/man/includes/section-features.md index 2161ad967f1..5d3ae324212 100644 --- a/src/doc/man/includes/section-features.md +++ b/src/doc/man/includes/section-features.md @@ -1,4 +1,4 @@ -=== Feature Selection +### Feature Selection The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the @@ -9,15 +9,21 @@ or all features if `--all-features` is specified. When no feature options are given, the `default` feature is activated for every selected package. -*--features* _FEATURES_:: - Space or comma separated list of features to activate. These features only - apply to the current directory's package. Features of direct dependencies - may be enabled with `/` syntax. This flag may be - specified multiple times, which enables all specified features. +{{#options}} -*--all-features*:: - Activate all available features of all selected packages. +{{#option "`--features` _features_" }} +Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with `/` syntax. This flag may be +specified multiple times, which enables all specified features. +{{/option}} -*--no-default-features*:: - Do not activate the `default` feature of the current directory's - package. +{{#option "`--all-features`" }} +Activate all available features of all selected packages. +{{/option}} + +{{#option "`--no-default-features`" }} +Do not activate the `default` feature of the current directory's package. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/section-options-common.md b/src/doc/man/includes/section-options-common.md index aa0e24f522f..2f9bad4f6d8 100644 --- a/src/doc/man/includes/section-options-common.md +++ b/src/doc/man/includes/section-options-common.md @@ -1,14 +1,21 @@ -*+TOOLCHAIN*:: - If Cargo has been installed with rustup, and the first argument to `cargo` - begins with `+`, it will be interpreted as a rustup toolchain name (such - as `+stable` or `+nightly`). - See the link:https://github.com/rust-lang/rustup/[rustup documentation] - for more information about how toolchain overrides work. - -*-h*:: -*--help*:: - Prints help information. - -*-Z* _FLAG_...:: - Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for - details. +### Common Options + +{{#options}} + +{{#option "`+`_toolchain_"}} +If Cargo has been installed with rustup, and the first argument to `cargo` +begins with `+`, it will be interpreted as a rustup toolchain name (such +as `+stable` or `+nightly`). +See the [rustup documentation](https://github.com/rust-lang/rustup/) +for more information about how toolchain overrides work. +{{/option}} + +{{#option "`-h`" "`--help`"}} +Prints help information. +{{/option}} + +{{#option "`-Z` _flag_"}} +Unstable (nightly-only) flags to Cargo. Run `cargo -Z help` for details. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/section-options-package.md b/src/doc/man/includes/section-options-package.md index c0cfbc35eef..4fa732dd328 100644 --- a/src/doc/man/includes/section-options-package.md +++ b/src/doc/man/includes/section-options-package.md @@ -1,7 +1,13 @@ +### Package Selection + By default, the package in the current working directory is selected. The `-p` flag can be used to choose a different package in a workspace. -*-p* _SPEC_:: -*--package* _SPEC_:: - The package to convert:lowercase[{actionverb}]. See man:cargo-pkgid[1] for - the SPEC format. +{{#options}} + +{{#option "`-p` _spec_" "`--package` _spec_" }} +The package to {{lower actionverb}}. See {{man "cargo-pkgid" 1}} for the SPEC +format. +{{/option}} + +{{/options}} diff --git a/src/doc/man/includes/section-package-selection.md b/src/doc/man/includes/section-package-selection.md index dbddfb9c021..0c4a8629ed0 100644 --- a/src/doc/man/includes/section-package-selection.md +++ b/src/doc/man/includes/section-package-selection.md @@ -1,3 +1,5 @@ +### Package Selection + By default, when no package selection options are given, the packages selected depend on the selected manifest file (based on the current working directory if `--manifest-path` is not given). If the manifest is the root of a workspace then @@ -9,19 +11,26 @@ The default members of a workspace can be set explicitly with the virtual workspace will include all workspace members (equivalent to passing `--workspace`), and a non-virtual workspace will include only the root crate itself. -*-p* _SPEC_...:: -*--package* _SPEC_...:: - {actionverb} only the specified packages. See man:cargo-pkgid[1] for the - SPEC format. This flag may be specified multiple times. +{{#options}} + +{{#option "`-p` _spec_..." "`--package` _spec_..."}} +{{actionverb}} only the specified packages. See {{man "cargo-pkgid" 1}} for the +SPEC format. This flag may be specified multiple times. +{{/option}} + +{{#option "`--workspace`" }} +{{actionverb}} all members in the workspace. +{{/option}} -*--workspace*:: - {actionverb} all members in the workspace. +{{#unless noall}} +{{#option "`--all`" }} +Deprecated alias for `--workspace`. +{{/option}} +{{/unless}} -ifndef::noall[] -*--all*:: - Deprecated alias for `--workspace`. -endif::noall[] +{{#option "`--exclude` _SPEC_..." }} +Exclude the specified packages. Must be used in conjunction with the +`--workspace` flag. This flag may be specified multiple times. +{{/option}} -*--exclude* _SPEC_...:: - Exclude the specified packages. Must be used in conjunction with the - `--workspace` flag. This flag may be specified multiple times. +{{/options}} diff --git a/src/doc/man/includes/section-profiles.md b/src/doc/man/includes/section-profiles.md index 85f208997f9..d0a407213cd 100644 --- a/src/doc/man/includes/section-profiles.md +++ b/src/doc/man/includes/section-profiles.md @@ -1,26 +1,16 @@ -== PROFILES +## PROFILES Profiles may be used to configure compiler options such as optimization levels -and debug settings. See -linkcargo:reference/profiles.html[the reference] -for more details. +and debug settings. See [the reference](../reference/profiles.html) for more +details. Profile selection depends on the target and crate being built. By default the `dev` or `test` profiles are used. If the `--release` flag is given, then the `release` or `bench` profiles are used. -[%autowidth] -|=== -|Target |Default Profile |`--release` Profile - -|lib, bin, example -|`dev` -|`release` - -|test, bench, or any target + - in "test" or "bench" mode -|`test` -|`bench` -|=== +Target | Default Profile | `--release` Profile +-------|-----------------|--------------------- +lib, bin, example | `dev` | `release` +test, bench, or any target in "test" or "bench" mode | `test` | `bench` Dependencies use the `dev`/`release` profiles. From 25291c6c3644d3ac3744ca6fc239469a2bc99300 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 1 Aug 2020 09:36:24 -0700 Subject: [PATCH 4/7] Remove old HTML generated man pages. --- src/doc/man/generated/cargo-bench.html | 545 ---------------- src/doc/man/generated/cargo-build.html | 494 -------------- src/doc/man/generated/cargo-check.html | 485 -------------- src/doc/man/generated/cargo-clean.html | 254 -------- src/doc/man/generated/cargo-doc.html | 448 ------------- src/doc/man/generated/cargo-fetch.html | 223 ------- src/doc/man/generated/cargo-fix.html | 569 ---------------- .../generated/cargo-generate-lockfile.html | 191 ------ src/doc/man/generated/cargo-help.html | 53 -- src/doc/man/generated/cargo-init.html | 263 -------- src/doc/man/generated/cargo-install.html | 461 ------------- .../man/generated/cargo-locate-project.html | 160 ----- src/doc/man/generated/cargo-login.html | 168 ----- src/doc/man/generated/cargo-metadata.html | 520 --------------- src/doc/man/generated/cargo-new.html | 256 -------- src/doc/man/generated/cargo-owner.html | 220 ------- src/doc/man/generated/cargo-package.html | 354 ---------- src/doc/man/generated/cargo-pkgid.html | 266 -------- src/doc/man/generated/cargo-publish.html | 338 ---------- src/doc/man/generated/cargo-run.html | 407 ------------ src/doc/man/generated/cargo-rustc.html | 469 -------------- src/doc/man/generated/cargo-rustdoc.html | 475 -------------- src/doc/man/generated/cargo-search.html | 166 ----- src/doc/man/generated/cargo-test.html | 613 ------------------ src/doc/man/generated/cargo-tree.html | 516 --------------- src/doc/man/generated/cargo-uninstall.html | 191 ------ src/doc/man/generated/cargo-update.html | 241 ------- src/doc/man/generated/cargo-vendor.html | 240 ------- .../man/generated/cargo-verify-project.html | 199 ------ src/doc/man/generated/cargo-version.html | 76 --- src/doc/man/generated/cargo-yank.html | 196 ------ src/doc/man/generated/cargo.html | 470 -------------- 32 files changed, 10527 deletions(-) delete mode 100644 src/doc/man/generated/cargo-bench.html delete mode 100644 src/doc/man/generated/cargo-build.html delete mode 100644 src/doc/man/generated/cargo-check.html delete mode 100644 src/doc/man/generated/cargo-clean.html delete mode 100644 src/doc/man/generated/cargo-doc.html delete mode 100644 src/doc/man/generated/cargo-fetch.html delete mode 100644 src/doc/man/generated/cargo-fix.html delete mode 100644 src/doc/man/generated/cargo-generate-lockfile.html delete mode 100644 src/doc/man/generated/cargo-help.html delete mode 100644 src/doc/man/generated/cargo-init.html delete mode 100644 src/doc/man/generated/cargo-install.html delete mode 100644 src/doc/man/generated/cargo-locate-project.html delete mode 100644 src/doc/man/generated/cargo-login.html delete mode 100644 src/doc/man/generated/cargo-metadata.html delete mode 100644 src/doc/man/generated/cargo-new.html delete mode 100644 src/doc/man/generated/cargo-owner.html delete mode 100644 src/doc/man/generated/cargo-package.html delete mode 100644 src/doc/man/generated/cargo-pkgid.html delete mode 100644 src/doc/man/generated/cargo-publish.html delete mode 100644 src/doc/man/generated/cargo-run.html delete mode 100644 src/doc/man/generated/cargo-rustc.html delete mode 100644 src/doc/man/generated/cargo-rustdoc.html delete mode 100644 src/doc/man/generated/cargo-search.html delete mode 100644 src/doc/man/generated/cargo-test.html delete mode 100644 src/doc/man/generated/cargo-tree.html delete mode 100644 src/doc/man/generated/cargo-uninstall.html delete mode 100644 src/doc/man/generated/cargo-update.html delete mode 100644 src/doc/man/generated/cargo-vendor.html delete mode 100644 src/doc/man/generated/cargo-verify-project.html delete mode 100644 src/doc/man/generated/cargo-version.html delete mode 100644 src/doc/man/generated/cargo-yank.html delete mode 100644 src/doc/man/generated/cargo.html diff --git a/src/doc/man/generated/cargo-bench.html b/src/doc/man/generated/cargo-bench.html deleted file mode 100644 index 3085d4be2ef..00000000000 --- a/src/doc/man/generated/cargo-bench.html +++ /dev/null @@ -1,545 +0,0 @@ -

NAME

-
-

cargo-bench - Execute benchmarks of a package

-
-
-

SYNOPSIS

-
-
-

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

-
-
-
-
-

DESCRIPTION

-
-
-

Compile and execute benchmarks.

-
-
-

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

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

Benchmarks are built with the --test option to rustc which creates an -executable with a main function that automatically runs all functions -annotated with the #[bench] attribute. Cargo passes the --bench flag to -the test harness to tell it to run only benchmarks.

-
-
-

The libtest harness may be disabled by setting harness = false in the target -manifest settings, in which case your code will need to provide its own main -function to handle running benchmarks.

-
-
-
-
-

Note: The -#[bench] attribute -is currently unstable and only available on the -nightly channel. -There are some packages available on -crates.io that may help with -running benchmarks on the stable channel, such as -Criterion.

-
-
-
-
-
-
-

OPTIONS

-
-
-

Benchmark Options

-
-
-
--no-run
-
-

Compile, but don’t run benchmarks.

-
-
--no-fail-fast
-
-

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

-
-
-
-
-
-

Package Selection

-
-

By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if ---manifest-path is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected.

-
-
-

The default members of a workspace can be set explicitly with the -workspace.default-members key in the root manifest. If this is not set, a -virtual workspace will include all workspace members (equivalent to passing ---workspace), and a non-virtual workspace will include only the root crate itself.

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

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

-
-
--workspace
-
-

Benchmark all members in the workspace.

-
-
--all
-
-

Deprecated alias for --workspace.

-
-
--exclude SPEC…​
-
-

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

-
-
-
-
-
-

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 targets in test mode that have the test = true manifest -flag set. By default this includes the library and binaries built as -unittests, and integration tests. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the test flag in the -manifest settings for the target.

-
-
--bench NAME…​
-
-

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

-
-
--benches
-
-

Benchmark all targets in benchmark mode that have the bench = true -manifest flag set. By default this includes the library and binaries built -as benchmarks, and bench targets. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the bench flag in the -manifest settings for the target.

-
-
--all-targets
-
-

Benchmark all targets. This is equivalent to specifying --lib --bins ---tests --benches --examples.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
-
-
-
-

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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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/man/generated/cargo-build.html b/src/doc/man/generated/cargo-build.html deleted file mode 100644 index 718dfd99740..00000000000 --- a/src/doc/man/generated/cargo-build.html +++ /dev/null @@ -1,494 +0,0 @@ -

NAME

-
-

cargo-build - Compile the current package

-
-
-

SYNOPSIS

-
-
-

cargo build [OPTIONS]

-
-
-
-
-

DESCRIPTION

-
-
-

Compile local packages and all of their dependencies.

-
-
-
-
-

OPTIONS

-
-
-

Package Selection

-
-

By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if ---manifest-path is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected.

-
-
-

The default members of a workspace can be set explicitly with the -workspace.default-members key in the root manifest. If this is not set, a -virtual workspace will include all workspace members (equivalent to passing ---workspace), and a non-virtual workspace will include only the root crate itself.

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

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

-
-
--workspace
-
-

Build all members in the workspace.

-
-
--all
-
-

Deprecated alias for --workspace.

-
-
--exclude SPEC…​
-
-

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

-
-
-
-
-
-

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 targets in test mode that have the test = true manifest -flag set. By default this includes the library and binaries built as -unittests, and integration tests. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the test flag in the -manifest settings for the target.

-
-
--bench NAME…​
-
-

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

-
-
--benches
-
-

Build all targets in benchmark mode that have the bench = true -manifest flag set. By default this includes the library and binaries built -as benchmarks, and bench targets. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the bench flag in the -manifest settings for the target.

-
-
--all-targets
-
-

Build all targets. This is equivalent to specifying --lib --bins ---tests --benches --examples.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Build optimized artifacts with the release profile. 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. -See https://github.com/rust-lang/cargo/issues/6790 for more information.

-
-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
--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. -See https://github.com/rust-lang/cargo/issues/5579 for more information.

-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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/man/generated/cargo-check.html b/src/doc/man/generated/cargo-check.html deleted file mode 100644 index e151265dc05..00000000000 --- a/src/doc/man/generated/cargo-check.html +++ /dev/null @@ -1,485 +0,0 @@ -

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 selected manifest file (based on the current working directory if ---manifest-path is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected.

-
-
-

The default members of a workspace can be set explicitly with the -workspace.default-members key in the root manifest. If this is not set, a -virtual workspace will include all workspace members (equivalent to passing ---workspace), and a non-virtual workspace will include only the root crate itself.

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

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

-
-
--workspace
-
-

Check all members in the workspace.

-
-
--all
-
-

Deprecated alias for --workspace.

-
-
--exclude SPEC…​
-
-

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

-
-
-
-
-
-

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 targets in test mode that have the test = true manifest -flag set. By default this includes the library and binaries built as -unittests, and integration tests. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the test flag in the -manifest settings for the target.

-
-
--bench NAME…​
-
-

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

-
-
--benches
-
-

Check all targets in benchmark mode that have the bench = true -manifest flag set. By default this includes the library and binaries built -as benchmarks, and bench targets. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the bench flag in the -manifest settings for the target.

-
-
--all-targets
-
-

Check all targets. This is equivalent to specifying --lib --bins ---tests --benches --examples.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Check optimized artifacts with the release profile. 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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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/man/generated/cargo-clean.html b/src/doc/man/generated/cargo-clean.html deleted file mode 100644 index dbc1e4a367a..00000000000 --- a/src/doc/man/generated/cargo-clean.html +++ /dev/null @@ -1,254 +0,0 @@ -

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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-doc.html b/src/doc/man/generated/cargo-doc.html deleted file mode 100644 index 33b6d6482ea..00000000000 --- a/src/doc/man/generated/cargo-doc.html +++ /dev/null @@ -1,448 +0,0 @@ -

NAME

-
-

cargo-doc - Build a package's documentation

-
-
-

SYNOPSIS

-
-
-

cargo doc [OPTIONS]

-
-
-
-
-

DESCRIPTION

-
-
-

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

-
-
-
-
-

OPTIONS

-
-
-

Documentation Options

-
-
-
--open
-
-

Open the docs in a browser after building them. This will use your default -browser unless you define another one in the BROWSER environment -variable.

-
-
--no-deps
-
-

Do not build documentation for dependencies.

-
-
--document-private-items
-
-

Include non-public items in the documentation.

-
-
-
-
-
-

Package Selection

-
-

By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if ---manifest-path is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected.

-
-
-

The default members of a workspace can be set explicitly with the -workspace.default-members key in the root manifest. If this is not set, a -virtual workspace will include all workspace members (equivalent to passing ---workspace), and a non-virtual workspace will include only the root crate itself.

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

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

-
-
--workspace
-
-

Document all members in the workspace.

-
-
--all
-
-

Deprecated alias for --workspace.

-
-
--exclude SPEC…​
-
-

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

-
-
-
-
-
-

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

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Document optimized artifacts with the release profile. 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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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/man/generated/cargo-fetch.html b/src/doc/man/generated/cargo-fetch.html deleted file mode 100644 index d37eebd1c40..00000000000 --- a/src/doc/man/generated/cargo-fetch.html +++ /dev/null @@ -1,223 +0,0 @@ -

NAME

-
-

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

-
-
-

SYNOPSIS

-
-
-

cargo fetch [OPTIONS]

-
-
-
-
-

DESCRIPTION

-
-
-

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

-
-
-

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

-
-
-

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

-
-
-

See also the cargo-prefetch -plugin which adds a command to download popular crates. This may be useful if -you plan to use Cargo without a network with the --offline flag.

-
-
-
-
-

OPTIONS

-
-
-

Fetch options

-
-
-
--target TRIPLE
-
-

Fetch for the given architecture. The default is the host -architecture. The general format of the triple is -<arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-fix.html b/src/doc/man/generated/cargo-fix.html deleted file mode 100644 index 20d9bcc9d77..00000000000 --- a/src/doc/man/generated/cargo-fix.html +++ /dev/null @@ -1,569 +0,0 @@ -

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.

-
-
-

cargo fix is only capable of fixing code that is normally compiled with -cargo check. If code is conditionally enabled with optional features, you -will need to enable those features for that code to be analyzed:

-
-
-
-
cargo fix --edition --features foo
-
-
-
-

Similarly, other cfg expressions like platform-specific code will need to -pass --target to fix code for the given target.

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

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

-
-
-
-
-

OPTIONS

-
-
-

Fix options

-
-
-
--broken-code
-
-

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

-
-
--edition
-
-

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

-
-
--edition-idioms
-
-

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

-
-
--allow-no-vcs
-
-

Fix code even if a VCS was not detected.

-
-
--allow-dirty
-
-

Fix code even if the working directory has changes.

-
-
--allow-staged
-
-

Fix code even if the working directory has staged changes.

-
-
-
-
-
-

Package Selection

-
-

By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if ---manifest-path is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected.

-
-
-

The default members of a workspace can be set explicitly with the -workspace.default-members key in the root manifest. If this is not set, a -virtual workspace will include all workspace members (equivalent to passing ---workspace), and a non-virtual workspace will include only the root crate itself.

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

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

-
-
--workspace
-
-

Fix all members in the workspace.

-
-
--all
-
-

Deprecated alias for --workspace.

-
-
--exclude SPEC…​
-
-

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

-
-
-
-
-
-

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 targets in test mode that have the test = true manifest -flag set. By default this includes the library and binaries built as -unittests, and integration tests. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the test flag in the -manifest settings for the target.

-
-
--bench NAME…​
-
-

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

-
-
--benches
-
-

Fix all targets in benchmark mode that have the bench = true -manifest flag set. By default this includes the library and binaries built -as benchmarks, and bench targets. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the bench flag in the -manifest settings for the target.

-
-
--all-targets
-
-

Fix all targets. This is equivalent to specifying --lib --bins ---tests --benches --examples.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Fix optimized artifacts with the release profile. 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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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/man/generated/cargo-generate-lockfile.html b/src/doc/man/generated/cargo-generate-lockfile.html deleted file mode 100644 index 467945a0aec..00000000000 --- a/src/doc/man/generated/cargo-generate-lockfile.html +++ /dev/null @@ -1,191 +0,0 @@ -

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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-help.html b/src/doc/man/generated/cargo-help.html deleted file mode 100644 index 0bdceebd1c9..00000000000 --- a/src/doc/man/generated/cargo-help.html +++ /dev/null @@ -1,53 +0,0 @@ -

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/man/generated/cargo-init.html b/src/doc/man/generated/cargo-init.html deleted file mode 100644 index 593596d34d7..00000000000 --- a/src/doc/man/generated/cargo-init.html +++ /dev/null @@ -1,263 +0,0 @@ -

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
-
-

This sets the publish field in Cargo.toml to the given registry name -which will restrict publishing only to that registry.

-
-

Registry names are defined in Cargo config files. -If not specified, the default registry defined by the registry.default -config key is used. If the default registry is not set and --registry is not -used, the publish field will not be set which means that publishing will not -be restricted.

-
-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-install.html b/src/doc/man/generated/cargo-install.html deleted file mode 100644 index 7093fa3e18b..00000000000 --- a/src/doc/man/generated/cargo-install.html +++ /dev/null @@ -1,461 +0,0 @@ -

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 executable [[bin]] or [[example]] targets can be -installed, and all executables are installed into the installation root’s -bin folder.

-
-
-

The installation root is determined, in order of precedence:

-
-
-
    -
  • -

    --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, --path, and --registry flags can -change this source. If the source contains more than one package (such as -crates.io or a git repository with multiple crates) the CRATE argument is -required to indicate which crate should be installed.

-
-
-

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

-
-
-

If the package is already installed, Cargo will reinstall it if the installed -version does not appear to be up-to-date. If any of the following values -change, then Cargo will reinstall the package:

-
-
-
    -
  • -

    The package version and source.

    -
    • -
  • -

    The set of binary names installed.

    -
    • -
  • -

    The chosen features.

    -
    • -
  • -

    The release mode (--debug).

    -
    • -
  • -

    The target (--target).

    -
    • -
-
-
-

Installing with --path will always build and install, unless there are -conflicting binaries from another package. The --force flag may be used to -force Cargo to always reinstall the package.

-
-
-

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

-
-
-

By default, the Cargo.lock file that is included with the package will be -ignored. This means that Cargo will recompute which versions of dependencies -to use, possibly using newer versions that have been released since the -package was published. The --locked flag can be used to force Cargo to use -the packaged Cargo.lock file if it is available. This may be useful for -ensuring reproducible builds, to use the exact same set of dependencies that -were available when the package was published. It may also be useful if a -newer version of a dependency is published that no longer builds on your -system, or has other problems. The downside to using --locked is that you -will not receive any fixes or updates to any dependency. Note that Cargo did -not start publishing Cargo.lock files until version 1.37, which means -packages published with prior versions will not have a Cargo.lock file -available.

-
-
-
-
-

OPTIONS

-
-
-

Install Options

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

Specify a version to install. This may be a -version requirement, like -~1.2, to have Cargo select the newest version from the given -requirement. If the version does not have a requirement operator (such as -^ or ~), then it must be in the form MAJOR.MINOR.PATCH, and will -install exactly that version; it is not treated as a caret requirement -like Cargo dependencies are.

-
-
--git URL
-
-

Git URL to install the specified crate from.

-
-
--branch BRANCH
-
-

Branch to use when installing from git.

-
-
--tag TAG
-
-

Tag to use when installing from git.

-
-
--rev SHA
-
-

Specific commit to use when installing from git.

-
-
--path PATH
-
-

Filesystem path to local crate to install.

-
-
--list
-
-

List all installed packages and their versions.

-
-
-f
-
--force
-
-

Force overwriting existing crates or binaries. This can be used if a -package has installed a binary with the same name as another package. This -is also useful if something has changed on the system that you want to -rebuild with, such as a newer version of rustc.

-
-
--no-track
-
-

By default, Cargo keeps track of the installed packages with a metadata -file stored in the installation root directory. This flag tells Cargo not -to use or create that file. With this flag, Cargo will refuse to overwrite -any existing files unless the --force flag is used. This also disables -Cargo’s ability to protect against multiple concurrent invocations of -Cargo installing at the same time.

-
-
--bin NAME…​
-
-

Install only the specified binary.

-
-
--bins
-
-

Install all binaries.

-
-
--example NAME…​
-
-

Install only the specified example.

-
-
--examples
-
-

Install all examples.

-
-
--root DIR
-
-

Directory to install packages into.

-
-
--registry REGISTRY
-
-

Name of the registry to use. Registry names are defined in Cargo config files. -If not specified, the default registry is used, which is defined by the -registry.default config key which defaults to crates-io.

-
-
--index INDEX
-
-

The URL of the registry index to use.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--target-dir DIRECTORY
-
-

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

-
-
--debug
-
-

Build with the dev profile instead the release profile.

-
-
-
-
-
-

Manifest Options

-
-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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 or upgrade a package from crates.io:

    -
    -
    -
    cargo install ripgrep
    -
    -
    -
    2. -
  2. -

    Install or reinstall the package in the current directory:

    -
    -
    -
    cargo install --path .
    -
    -
    -
    3. -
  3. -

    View the list of installed packages:

    -
    -
    -
    cargo install --list
    -
    -
    -
    4. -
-
-
-
-
-

SEE ALSO

-
-
-

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

-
-
-
\ No newline at end of file diff --git a/src/doc/man/generated/cargo-locate-project.html b/src/doc/man/generated/cargo-locate-project.html deleted file mode 100644 index 25f83cc91f6..00000000000 --- a/src/doc/man/generated/cargo-locate-project.html +++ /dev/null @@ -1,160 +0,0 @@ -

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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-login.html b/src/doc/man/generated/cargo-login.html deleted file mode 100644 index 7037f025de8..00000000000 --- a/src/doc/man/generated/cargo-login.html +++ /dev/null @@ -1,168 +0,0 @@ -

NAME

-
-

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

-
-
-

SYNOPSIS

-
-
-

cargo login [OPTIONS] [TOKEN]

-
-
-
-
-

DESCRIPTION

-
-
-

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

-
-
-

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

-
-
-

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

-
-
-

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

-
-
-
-
-

OPTIONS

-
-
-

Login Options

-
-
-
--registry REGISTRY
-
-

Name of the registry to use. Registry names are defined in Cargo config files. -If not specified, the default registry is used, which is defined by the -registry.default config key which defaults to crates-io.

-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-metadata.html b/src/doc/man/generated/cargo-metadata.html deleted file mode 100644 index 9a12c0591b0..00000000000 --- a/src/doc/man/generated/cargo-metadata.html +++ /dev/null @@ -1,520 +0,0 @@ -

NAME

-
-

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

-
-
-

SYNOPSIS

-
-
-

cargo metadata [OPTIONS]

-
-
-
-
-

DESCRIPTION

-
-
-

Output JSON to stdout containing information about the workspace members and -resolved dependencies of the current package.

-
-
-

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

-
-
-

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

-
-
-
-
-

OUTPUT FORMAT

-
-
-

The output has the following format:

-
-
-
-
{
-    /* Array of all packages in the workspace.
-       It also includes all feature-enabled dependencies unless --no-deps is used.
-    */
-    "packages": [
-        {
-            /* The name of the package. */
-            "name": "my-package",
-            /* The version of the package. */
-            "version": "0.1.0",
-            /* The Package ID, a unique identifier for referring to the package. */
-            "id": "my-package 0.1.0 (path+file:///path/to/my-package)",
-            /* The license value from the manifest, or null. */
-            "license": "MIT/Apache-2.0",
-            /* The license-file value from the manifest, or null. */
-            "license_file": "LICENSE",
-            /* The description value from the manifest, or null. */
-            "description": "Package description.",
-            /* The source ID of the package. This represents where
-               a package is retrieved from.
-               This is null for path dependencies and workspace members.
-               For other dependencies, it is a string with the format:
-               - "registry+URL" for registry-based dependencies.
-                 Example: "registry+https://github.com/rust-lang/crates.io-index"
-               - "git+URL" for git-based dependencies.
-                 Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c"
-            */
-            "source": null,
-            /* Array of dependencies declared in the package's manifest. */
-            "dependencies": [
-                {
-                    /* The name of the dependency. */
-                    "name": "bitflags",
-                    /* The source ID of the dependency. May be null, see
-                       description for the package source.
-                    */
-                    "source": "registry+https://github.com/rust-lang/crates.io-index",
-                    /* The version requirement for the dependency.
-                       Dependencies without a version requirement have a value of "*".
-                    */
-                    "req": "^1.0",
-                    /* The dependency kind.
-                       "dev", "build", or null for a normal dependency.
-                    */
-                    "kind": null,
-                    /* If the dependency is renamed, this is the new name for
-                       the dependency as a string.  null if it is not renamed.
-                    */
-                    "rename": null,
-                    /* Boolean of whether or not this is an optional dependency. */
-                    "optional": false,
-                    /* Boolean of whether or not default features are enabled. */
-                    "uses_default_features": true,
-                    /* Array of features enabled. */
-                    "features": [],
-                    /* The target platform for the dependency.
-                       null if not a target dependency.
-                    */
-                    "target": "cfg(windows)",
-                    /* A string of the URL of the registry this dependency is from.
-                       If not specified or null, the dependency is from the default
-                       registry (crates.io).
-                    */
-                    "registry": null
-                }
-            ],
-            /* Array of Cargo targets. */
-            "targets": [
-                {
-                    /* Array of target kinds.
-                       - lib targets list the `crate-type` values from the
-                         manifest such as "lib", "rlib", "dylib",
-                         "proc-macro", etc. (default ["lib"])
-                       - binary is ["bin"]
-                       - example is ["example"]
-                       - integration test is ["test"]
-                       - benchmark is ["bench"]
-                       - build script is ["custom-build"]
-                    */
-                    "kind": [
-                        "bin"
-                    ],
-                    /* Array of crate types.
-                       - lib and example libraries list the `crate-type` values
-                         from the manifest such as "lib", "rlib", "dylib",
-                         "proc-macro", etc. (default ["lib"])
-                       - all other target kinds are ["bin"]
-                    */
-                    "crate_types": [
-                        "bin"
-                    ],
-                    /* The name of the target. */
-                    "name": "my-package",
-                    /* Absolute path to the root source file of the target. */
-                    "src_path": "/path/to/my-package/src/main.rs",
-                    /* The Rust edition of the target.
-                       Defaults to the package edition.
-                    */
-                    "edition": "2018",
-                    /* Array of required features.
-                       This property is not included if no required features are set.
-                    */
-                    "required-features": ["feat1"],
-                    /* Whether or not this target has doc tests enabled, and
-                       the target is compatible with doc testing.
-                    */
-                    "doctest": false,
-                    /* Whether or not this target should be built and run with `--test`
-                    */
-                    "test": true
-                }
-            ],
-            /* Set of features defined for the package.
-               Each feature maps to an array of features or dependencies it
-               enables.
-            */
-            "features": {
-                "default": [
-                    "feat1"
-                ],
-                "feat1": [],
-                "feat2": []
-            },
-            /* Absolute path to this package's manifest. */
-            "manifest_path": "/path/to/my-package/Cargo.toml",
-            /* Package metadata.
-               This is null if no metadata is specified.
-            */
-            "metadata": {
-                "docs": {
-                    "rs": {
-                        "all-features": true
-                    }
-                }
-            },
-            /* List of registries to which this package may be published.
-               Publishing is unrestricted if null, and forbidden if an empty array. */
-            "publish": [
-                "crates-io"
-            ],
-            /* Array of authors from the manifest.
-               Empty array if no authors specified.
-            */
-            "authors": [
-                "Jane Doe <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",
-            /* Optional string that is the name of a native library the package
-               is linking to.
-            */
-            "links": null,
-        }
-    ],
-    /* Array of members of the workspace.
-       Each entry is the Package ID for the package.
-    */
-    "workspace_members": [
-        "my-package 0.1.0 (path+file:///path/to/my-package)",
-    ],
-    // The resolved dependency graph for the entire workspace. The enabled
-    // features are based on the enabled features for the "current" package.
-    // Inactivated optional dependencies are not listed.
-    //
-    // This is null if --no-deps is specified.
-    //
-    // By default, this includes all dependencies for all target platforms.
-    // The `--filter-platform` flag may be used to narrow to a specific
-    // target triple.
-    "resolve": {
-        /* Array of nodes within the dependency graph.
-           Each node is a package.
-        */
-        "nodes": [
-            {
-                /* The Package ID of this node. */
-                "id": "my-package 0.1.0 (path+file:///path/to/my-package)",
-                /* The dependencies of this package, an array of Package IDs. */
-                "dependencies": [
-                    "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)"
-                ],
-                /* The dependencies of this package. This is an alternative to
-                   "dependencies" which contains additional information. In
-                   particular, this handles renamed dependencies.
-                */
-                "deps": [
-                    {
-                        /* The name of the dependency's library target.
-                           If this is a renamed dependency, this is the new
-                           name.
-                        */
-                        "name": "bitflags",
-                        /* The Package ID of the dependency. */
-                        "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)",
-                        /* Array of dependency kinds. Added in Cargo 1.40. */
-                        "dep_kinds": [
-                            {
-                                /* The dependency kind.
-                                   "dev", "build", or null for a normal dependency.
-                                */
-                                "kind": null,
-                                /* The target platform for the dependency.
-                                   null if not a target dependency.
-                                */
-                                "target": "cfg(windows)"
-                            }
-                        ]
-                    }
-                ],
-                /* Array of features enabled on this package. */
-                "features": [
-                    "default"
-                ]
-            }
-        ],
-        /* The root package of the workspace.
-           This is null if this is a virtual workspace. Otherwise it is
-           the Package ID of the root package.
-        */
-        "root": "my-package 0.1.0 (path+file:///path/to/my-package)"
-    },
-    /* The absolute path to the build directory where Cargo places its output. */
-    "target_directory": "/path/to/my-package/target",
-    /* The version of the schema for this metadata structure.
-       This will be changed if incompatible changes are ever made.
-    */
-    "version": 1,
-    /* The absolute path to the root of the workspace. */
-    "workspace_root": "/path/to/my-package"
-    /* Workspace metadata.
-       This is null if no metadata is specified. */
-    "metadata": {
-        "docs": {
-            "rs": {
-                "all-features": true
-            }
-        }
-    }
-}
-
-
-
-
-
-

OPTIONS

-
-
-

Output Options

-
-
-
--no-deps
-
-

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

-
-
--format-version VERSION
-
-

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

-
-
--filter-platform TRIPLE
-
-

This filters the resolve output to only include dependencies for the -given target triple. Without this flag, the resolve includes all targets.

-
-

Note that the dependencies listed in the "packages" array still includes all -dependencies. Each package definition is intended to be an unaltered -reproduction of the information within Cargo.toml.

-
-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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)

-
-
-
diff --git a/src/doc/man/generated/cargo-new.html b/src/doc/man/generated/cargo-new.html deleted file mode 100644 index 4ea179f9463..00000000000 --- a/src/doc/man/generated/cargo-new.html +++ /dev/null @@ -1,256 +0,0 @@ -

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
-
-

This sets the publish field in Cargo.toml to the given registry name -which will restrict publishing only to that registry.

-
-

Registry names are defined in Cargo config files. -If not specified, the default registry defined by the registry.default -config key is used. If the default registry is not set and --registry is not -used, the publish field will not be set which means that publishing will not -be restricted.

-
-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-owner.html b/src/doc/man/generated/cargo-owner.html deleted file mode 100644 index c7fb23f7163..00000000000 --- a/src/doc/man/generated/cargo-owner.html +++ /dev/null @@ -1,220 +0,0 @@ -

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…​
-
-

Invite the given user or team as an owner.

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

Remove the given user or team as an owner.

-
-
-l
-
--list
-
-

List owners of a crate.

-
-
--token TOKEN
-
-

API token to use when authenticating. This overrides the token stored in -the credentials file (which is created by cargo-login(1)).

-
-

Cargo config environment variables can be -used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the CARGO_REGISTRY_TOKEN environment -variable. Tokens for other registries may be specified with environment -variables of the form CARGO_REGISTRIES_NAME_TOKEN where NAME is the name -of the registry in all capital letters.

-
-
-
--index INDEX
-
-

The URL of the registry index to use.

-
-
--registry REGISTRY
-
-

Name of the registry to use. Registry names are defined in Cargo config files. -If not specified, the default registry is used, which is defined by the -registry.default config key which defaults to crates-io.

-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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. -

    Invite 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/man/generated/cargo-package.html b/src/doc/man/generated/cargo-package.html deleted file mode 100644 index 091b6e36006..00000000000 --- a/src/doc/man/generated/cargo-package.html +++ /dev/null @@ -1,354 +0,0 @@ -

NAME

-
-

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

-
-
-

SYNOPSIS

-
-
-

cargo package [OPTIONS]

-
-
-
-
-

DESCRIPTION

-
-
-

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

-
-
-
    -
  1. -

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

    -
    -
      -
    • -

      Path dependencies are not allowed unless they have a version key. Cargo -will ignore the path key for dependencies in published packages. -dev-dependencies do not have this restriction.

      -
      • -
    -
    -
    2. -
  2. -

    Create the compressed .crate file.

    -
    -
      -
    • -

      The original Cargo.toml file is rewritten and normalized.

      -
      • -
    • -

      [patch], [replace], and [workspace] sections are removed from the -manifest.

      -
      • -
    • -

      Cargo.lock is automatically included if the package contains an -executable binary or example target. cargo-install(1) will use the -packaged lock file if the --locked flag is used.

      -
      • -
    • -

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

      -
      • -
    -
    -
    3. -
  3. -

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

    -
    -
      -
    • -

      This will rebuild your package from scratch to ensure that it can be -built from a pristine state. The --no-verify flag can be used to skip -this step.

      -
      • -
    -
    -
    4. -
  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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--target-dir DIRECTORY
-
-

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

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

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

-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-pkgid.html b/src/doc/man/generated/cargo-pkgid.html deleted file mode 100644 index b1ab862d86a..00000000000 --- a/src/doc/man/generated/cargo-pkgid.html +++ /dev/null @@ -1,266 +0,0 @@ -

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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-publish.html b/src/doc/man/generated/cargo-publish.html deleted file mode 100644 index 04715c65106..00000000000 --- a/src/doc/man/generated/cargo-publish.html +++ /dev/null @@ -1,338 +0,0 @@ -

NAME

-
-

cargo-publish - Upload a package to the registry

-
-
-

SYNOPSIS

-
-
-

cargo publish [OPTIONS]

-
-
-
-
-

DESCRIPTION

-
-
-

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

-
-
-
    -
  1. -

    Performs a few checks, including:

    -
    -
      -
    • -

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

      -
      • -
    -
    -
    2. -
  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. This overrides the token stored in -the credentials file (which is created by cargo-login(1)).

-
-

Cargo config environment variables can be -used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the CARGO_REGISTRY_TOKEN environment -variable. Tokens for other registries may be specified with environment -variables of the form CARGO_REGISTRIES_NAME_TOKEN where NAME is the name -of the registry in all capital letters.

-
-
-
--no-verify
-
-

Don’t verify the contents by building them.

-
-
--allow-dirty
-
-

Allow working directories with uncommitted VCS changes to be packaged.

-
-
--index INDEX
-
-

The URL of the registry index to use.

-
-
--registry REGISTRY
-
-

Name of the registry to use. Registry names are defined in Cargo config files. -If not specified, the default registry is used, which is defined by the -registry.default config key which defaults to crates-io.

-
-
-
-
-
-

Compilation Options

-
-
-
--target TRIPLE
-
-

Publish for the given architecture. The default is the host -architecture. The general format of the triple is -<arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--target-dir DIRECTORY
-
-

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

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

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

-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-run.html b/src/doc/man/generated/cargo-run.html deleted file mode 100644 index c2cc8a61a66..00000000000 --- a/src/doc/man/generated/cargo-run.html +++ /dev/null @@ -1,407 +0,0 @@ -

NAME

-
-

cargo-run - Run the current package

-
-
-

SYNOPSIS

-
-
-

cargo run [OPTIONS] [-- ARGS]

-
-
-
-
-

DESCRIPTION

-
-
-

Run a binary or example of the local package.

-
-
-

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

-
-
-
-
-

OPTIONS

-
-
-

Package Selection

-
-

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

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

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

-
-
-
-
-
-

Target Selection

-
-

When no target selection options are given, cargo run will run the binary -target. If there are multiple binary targets, you must pass a target flag to -choose one. Or, the default-run field may be specified in the [package] -section of Cargo.toml to choose the name of the binary to run by default.

-
-
-
-
--bin NAME
-
-

Run the specified binary.

-
-
--example NAME
-
-

Run the specified example.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Run optimized artifacts with the release profile. 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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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 (assuming only one binary):

    -
    -
    -
    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/man/generated/cargo-rustc.html b/src/doc/man/generated/cargo-rustc.html deleted file mode 100644 index 5957b518ea8..00000000000 --- a/src/doc/man/generated/cargo-rustc.html +++ /dev/null @@ -1,469 +0,0 @@ -

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 targets in test mode that have the test = true manifest -flag set. By default this includes the library and binaries built as -unittests, and integration tests. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the test flag in the -manifest settings for the target.

-
-
--bench NAME…​
-
-

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

-
-
--benches
-
-

Build all targets in benchmark mode that have the bench = true -manifest flag set. By default this includes the library and binaries built -as benchmarks, and bench targets. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the bench flag in the -manifest settings for the target.

-
-
--all-targets
-
-

Build all targets. This is equivalent to specifying --lib --bins ---tests --benches --examples.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Build optimized artifacts with the release profile. 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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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/man/generated/cargo-rustdoc.html b/src/doc/man/generated/cargo-rustdoc.html deleted file mode 100644 index c4673dda770..00000000000 --- a/src/doc/man/generated/cargo-rustdoc.html +++ /dev/null @@ -1,475 +0,0 @@ -

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 config value.

-
-
-
-
-

OPTIONS

-
-
-

Documentation Options

-
-
-
--open
-
-

Open the docs in a browser after building them. This will use your default -browser unless you define another one in the BROWSER environment -variable.

-
-
-
-
-
-

Package Selection

-
-

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 targets in test mode that have the test = true manifest -flag set. By default this includes the library and binaries built as -unittests, and integration tests. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the test flag in the -manifest settings for the target.

-
-
--bench NAME…​
-
-

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

-
-
--benches
-
-

Document all targets in benchmark mode that have the bench = true -manifest flag set. By default this includes the library and binaries built -as benchmarks, and bench targets. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the bench flag in the -manifest settings for the target.

-
-
--all-targets
-
-

Document all targets. This is equivalent to specifying --lib --bins ---tests --benches --examples.

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Document optimized artifacts with the release profile. 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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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/man/generated/cargo-search.html b/src/doc/man/generated/cargo-search.html deleted file mode 100644 index 9f33fa22546..00000000000 --- a/src/doc/man/generated/cargo-search.html +++ /dev/null @@ -1,166 +0,0 @@ -

NAME

-
-

cargo-search - Search packages in crates.io

-
-
-

SYNOPSIS

-
-
-

cargo search [OPTIONS] [QUERY…​]

-
-
-
-
-

DESCRIPTION

-
-
-

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

-
-
-
-
-

OPTIONS

-
-
-

Search Options

-
-
-
--limit LIMIT
-
-

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

-
-
--index INDEX
-
-

The URL of the registry index to use.

-
-
--registry REGISTRY
-
-

Name of the registry to use. Registry names are defined in Cargo config files. -If not specified, the default registry is used, which is defined by the -registry.default config key which defaults to crates-io.

-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-test.html b/src/doc/man/generated/cargo-test.html deleted file mode 100644 index ee87f3cba85..00000000000 --- a/src/doc/man/generated/cargo-test.html +++ /dev/null @@ -1,613 +0,0 @@ -

NAME

-
-

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

-
-
-

SYNOPSIS

-
-
-

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

-
-
-
-
-

DESCRIPTION

-
-
-

Compile and execute unit and integration tests.

-
-
-

The test filtering argument TESTNAME and all the arguments following the two -dashes (--) are passed to the test binaries and thus to libtest (rustc’s -built in unit-test and micro-benchmarking framework). If you’re passing -arguments to both Cargo and the binary, the ones after -- go to the binary, -the ones before go to Cargo. For details about libtest’s arguments see the -output of cargo test -- --help.

-
-
-

As an example, this will filter for tests with foo in their name and run them -on 3 threads in parallel:

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

Tests are built with the --test option to rustc which creates an -executable with a main function that automatically runs all functions -annotated with the #[test] attribute in multiple threads. #[bench] -annotated functions will also be run with one iteration to verify that they -are functional.

-
-
-

The libtest harness may be disabled by setting harness = false in the target -manifest settings, in which case your code will need to provide its own main -function to handle running tests.

-
-
-

Documentation tests are also run by default, which is handled by rustdoc. It -extracts code samples from documentation comments and executes them. See the -rustdoc book for more information on -writing doc tests.

-
-
-
-
-

OPTIONS

-
-
-

Test Options

-
-
-
--no-run
-
-

Compile, but don’t run tests.

-
-
--no-fail-fast
-
-

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

-
-
-
-
-
-

Package Selection

-
-

By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if ---manifest-path is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected.

-
-
-

The default members of a workspace can be set explicitly with the -workspace.default-members key in the root manifest. If this is not set, a -virtual workspace will include all workspace members (equivalent to passing ---workspace), and a non-virtual workspace will include only the root crate itself.

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

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

-
-
--workspace
-
-

Test all members in the workspace.

-
-
--all
-
-

Deprecated alias for --workspace.

-
-
--exclude SPEC…​
-
-

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

-
-
-
-
-
-

Target Selection

-
-

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

-
-
-
    -
  • -

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

    -
    • -
  • -

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

    -
    • -
  • -

    examples — to ensure they compile

    -
    • -
  • -

    lib as a unit test

    -
    • -
  • -

    bins as unit tests

    -
    • -
  • -

    integration tests

    -
    • -
  • -

    doc tests for the lib target

    -
    • -
-
-
-

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

-
-
-

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

-
-
-

Binary targets are automatically built if there is an integration test or -benchmark. This allows an integration test to execute the binary to exercise -and test its behavior. The CARGO_BIN_EXE_<name> -environment variable -is set when the integration test is built so that it can use the -env macro to locate the -executable.

-
-
-

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 targets in test mode that have the test = true manifest -flag set. By default this includes the library and binaries built as -unittests, and integration tests. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the test flag in the -manifest settings for the target.

-
-
--bench NAME…​
-
-

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

-
-
--benches
-
-

Test all targets in benchmark mode that have the bench = true -manifest flag set. By default this includes the library and binaries built -as benchmarks, and bench targets. Be aware that this will also build any -required dependencies, so the lib target may be built twice (once as a -benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the bench flag in the -manifest settings for the target.

-
-
--all-targets
-
-

Test all targets. This is equivalent to specifying --lib --bins ---tests --benches --examples.

-
-
--doc
-
-

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

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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>. Run rustc --print target-list for a -list of supported targets.

-
-

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

-
-
-

Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -build cache documentation for more details.

-
-
-
--release
-
-

Test optimized artifacts with the release profile. 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. Can be specified multiple times -and consists of comma-separated values. Valid values:

-
-
    -
  • -

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

    -
    • -
  • -

    short: Emit shorter, human-readable text messages.

    -
    • -
  • -

    json: Emit JSON messages to stdout. See -the reference -for more details.

    -
    • -
  • -

    json-diagnostic-short: Ensure the rendered field of JSON messages contains -the "short" rendering from rustc.

    -
    • -
  • -

    json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages -contains embedded ANSI color codes for respecting rustc’s default color -scheme.

    -
    • -
  • -

    json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in -in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others -coming from rustc are still emitted.

    -
    • -
-
-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-

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, or any target
- in "test" or "bench" mode

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 tests whose names match against a filter string:

    -
    -
    -
    cargo test name_filter
    -
    -
    -
    3. -
  3. -

    Run only a specific test within a specific integration test:

    -
    -
    -
    cargo test --test int_test_name -- modname::test_name
    -
    -
    -
    4. -
-
-
-
-
-

SEE ALSO

-
-
-

cargo(1), cargo-bench(1)

-
-
-
\ No newline at end of file diff --git a/src/doc/man/generated/cargo-tree.html b/src/doc/man/generated/cargo-tree.html deleted file mode 100644 index a9bee7b3015..00000000000 --- a/src/doc/man/generated/cargo-tree.html +++ /dev/null @@ -1,516 +0,0 @@ -

NAME

-
-

cargo-tree - Display a tree visualization of a dependency graph

-
-
-

SYNOPSIS

-
-
-

cargo tree [OPTIONS]

-
-
-
-
-

DESCRIPTION

-
-
-

This command will display a tree of dependencies to the terminal. An example -of a simple project that depends on the "rand" package:

-
-
-
-
myproject v0.1.0 (/myproject)
-└── rand v0.7.3
-    ├── getrandom v0.1.14
-    │   ├── cfg-if v0.1.10
-    │   └── libc v0.2.68
-    ├── libc v0.2.68 (*)
-    ├── rand_chacha v0.2.2
-    │   ├── ppv-lite86 v0.2.6
-    │   └── rand_core v0.5.1
-    │       └── getrandom v0.1.14 (*)
-    └── rand_core v0.5.1 (*)
-[build-dependencies]
-└── cc v1.0.50
-
-
-
-

Packages marked with (*) have been "de-duplicated". The dependencies for the -package have already been shown elswhere in the graph, and so are not -repeated. Use the --no-dedupe option to repeat the duplicates.

-
-
-

The -e flag can be used to select the dependency kinds to display. The -"features" kind changes the output to display the features enabled by -each dependency. For example, cargo tree -e features:

-
-
-
-
myproject v0.1.0 (/myproject)
-└── log feature "serde"
-    └── log v0.4.8
-        ├── serde v1.0.106
-        └── cfg-if feature "default"
-            └── cfg-if v0.1.10
-
-
-
-

In this tree, myproject depends on log with the serde feature. log in -turn depends on cfg-if with "default" features. When using -e features it -can be helpful to use -i flag to show how the features flow into a package. -See the examples below for more detail.

-
-
-
-
-

OPTIONS

-
-
-

Tree Options

-
-
-
-i SPEC
-
--invert SPEC
-
-

Show the reverse dependencies for the given package. This flag will invert -the tree and display the packages that depend on the given package.

-
-

Note that in a workspace, by default it will only display the package’s -reverse dependencies inside the tree of the workspace member in the current -directory. The --workspace flag can be used to extend it so that it will -show the package’s reverse dependencies across the entire workspace. The -p -flag can be used to display the package’s reverse dependencies only with the -subtree of the package given to -p.

-
-
-
--no-dedupe
-
-

Do not de-duplicate repeated dependencies. Usually, when a package has -already displayed its dependencies, further occurrences will not -re-display its dependencies, and will include a (*) to indicate it has -already been shown. This flag will cause those duplicates to be repeated.

-
-
-d
-
--duplicates
-
-

Show only dependencies which come in multiple versions (implies ---invert). When used with the -p flag, only shows duplicates within -the subtree of the given package.

-
-

It can be beneficial for build times and executable sizes to avoid building -that same package multiple times. This flag can help identify the offending -packages. You can then investigate if the package that depends on the -duplicate with the older version can be updated to the newer version so that -only one instance is built.

-
-
-
-e KINDS
-
--edges KINDS
-
-

The dependency kinds to display. Takes a comma separated list of values:

-
-
    -
  • -

    all — Show all edge kinds.

    -
    • -
  • -

    normal — Show normal dependencies.

    -
    • -
  • -

    build — Show build dependencies.

    -
    • -
  • -

    dev — Show development dependencies.

    -
    • -
  • -

    features — Show features enabled by each dependency. If this is -the only kind given, then it will automatically include the other -dependency kinds.

    -
    • -
  • -

    no-normal — Do not include normal dependencies.

    -
    • -
  • -

    no-build — Do not include build dependencies.

    -
    • -
  • -

    no-dev — Do not include development dependencies.

    -
    • -
-
-
-

The no- prefixed options cannot be mixed with the other dependency kinds.

-
-
-

The default is normal,build,dev.

-
-
-
--target TRIPLE
-
-

Filter dependencies matching the given target-triple. -The default is the host platform. Use the value all to include all -targets.

-
-
-
-
-
-

Tree Formatting Options

-
-
-
--charset CHARSET
-
-

Chooses the character set to use for the tree. Valid values are "utf8" or -"ascii". Default is "utf8".

-
-
-f FORMAT
-
--format FORMAT
-
-

Set the format string for each package. The default is "{p}".

-
-

This is an arbitrary string which will be used to display each package. The following -strings will be replaced with the corresponding value:

-
-
-
    -
  • -

    {p} — The package name.

    -
    • -
  • -

    {l} — The package license.

    -
    • -
  • -

    {r} — The package repository URL.

    -
    • -
  • -

    {f} — Comma-separated list of package features that are enabled.

    -
    • -
-
-
-
--prefix PREFIX
-
-

Sets how each line is displayed. The PREFIX value can be one of:

-
-
    -
  • -

    indent (default) — Shows each line indented as a tree.

    -
    • -
  • -

    depth — Show as a list, with the numeric depth printed before each entry.

    -
    • -
  • -

    none — Show as a flat list.

    -
    • -
-
-
-
-
-
-
-

Package Selection

-
-

By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if ---manifest-path is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected.

-
-
-

The default members of a workspace can be set explicitly with the -workspace.default-members key in the root manifest. If this is not set, a -virtual workspace will include all workspace members (equivalent to passing ---workspace), and a non-virtual workspace will include only the root crate itself.

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

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

-
-
--workspace
-
-

Display all members in the workspace.

-
-
--exclude SPEC…​
-
-

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

-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
-
-
-
-

Feature Selection

-
-

The feature flags allow you to control the enabled features for the "current" -package. The "current" package is the package in the current directory, or the -one specified in --manifest-path. If running in the root of a virtual -workspace, then the default features are selected for all workspace members, -or all features if --all-features is specified.

-
-
-

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

-
-
-
-
--features FEATURES
-
-

Space or comma separated list of features to activate. These features only -apply to the current directory’s package. Features of direct dependencies -may be enabled with <dep-name>/<feature-name> syntax. This flag may be -specified multiple times, which enables all specified features.

-
-
--all-features
-
-

Activate all available features of all selected packages.

-
-
--no-default-features
-
-

Do not activate the default feature of the 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.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-
-
-

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 tree for the package in the current directory:

    -
    -
    -
    cargo tree
    -
    -
    -
    2. -
  2. -

    Display all the packages that depend on the syn package:

    -
    -
    -
    cargo tree -i syn
    -
    -
    -
    3. -
  3. -

    Show the features enabled on each package:

    -
    -
    -
    cargo tree --format "{p} {f}"
    -
    -
    -
    4. -
  4. -

    Show all packages that are built multiple times. This can happen if multiple -semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0).

    -
    -
    -
    cargo tree -d
    -
    -
    -
    5. -
  5. -

    Explain why features are enabled for the syn package:

    -
    -
    -
    cargo tree -e features -i syn
    -
    -
    -
    -

    The -e features flag is used to show features. The -i flag is used to -invert the graph so that it displays the packages that depend on syn. An -example of what this would display:

    -
    -
    -
    -
    syn v1.0.17
-├── syn feature "clone-impls"
-│   └── syn feature "default"
-│       └── rustversion v1.0.2
-│           └── rustversion feature "default"
-│               └── myproject v0.1.0 (/myproject)
-│                   └── myproject feature "default" (command-line)
-├── syn feature "default" (*)
-├── syn feature "derive"
-│   └── syn feature "default" (*)
-├── syn feature "full"
-│   └── rustversion v1.0.2 (*)
-├── syn feature "parsing"
-│   └── syn feature "default" (*)
-├── syn feature "printing"
-│   └── syn feature "default" (*)
-├── syn feature "proc-macro"
-│   └── syn feature "default" (*)
-└── syn feature "quote"
-    ├── syn feature "printing" (*)
-    └── syn feature "proc-macro" (*)
    -
    -
    -
    -

    To read this graph, you can follow the chain for each feature from the root to -see why it is included. For example, the "full" feature is added by the -rustversion crate which is included from myproject (with the default -features), and myproject is the package selected on the command-line. All -of the other syn features are added by the "default" feature ("quote" is -added by "printing" and "proc-macro", both of which are default features).

    -
    -
    -

    If you’re having difficulty cross-referencing the de-duplicated (*) entries, -try with the --no-dedupe flag to get the full output.

    -
    -
    6. -
-
-
-
-
-

SEE ALSO

-
-
-

cargo(1), cargo-metadata(1)

-
-
-
\ No newline at end of file diff --git a/src/doc/man/generated/cargo-uninstall.html b/src/doc/man/generated/cargo-uninstall.html deleted file mode 100644 index 1ebfba2490f..00000000000 --- a/src/doc/man/generated/cargo-uninstall.html +++ /dev/null @@ -1,191 +0,0 @@ -

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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-update.html b/src/doc/man/generated/cargo-update.html deleted file mode 100644 index 9cd2a3b560a..00000000000 --- a/src/doc/man/generated/cargo-update.html +++ /dev/null @@ -1,241 +0,0 @@ -

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).

-
-
--dry-run
-
-

Displays what would be updated, but doesn’t actually write the lockfile.

-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-vendor.html b/src/doc/man/generated/cargo-vendor.html deleted file mode 100644 index 9e4a062e9e7..00000000000 --- a/src/doc/man/generated/cargo-vendor.html +++ /dev/null @@ -1,240 +0,0 @@ -

NAME

-
-

cargo-vendor - Vendor all dependencies locally

-
-
-

SYNOPSIS

-
-
-

cargo vendor [OPTIONS] [PATH]

-
-
-
-
-

DESCRIPTION

-
-
-

This cargo subcommand will vendor all crates.io and git dependencies for a -project into the specified directory at <path>. After this command completes -the vendor directory specified by <path> will contain all remote sources from -dependencies specified. Additional manifests beyond the default one can be -specified with the -s option.

-
-
-

The cargo vendor command will also print out the configuration necessary -to use the vendored sources, which you will need to add to .cargo/config.toml.

-
-
-
-
-

OPTIONS

-
-
-

Vendor Options

-
-
-
-s MANIFEST
-
--sync MANIFEST
-
-

Specify extra Cargo.toml manifests to workspaces which should also be -vendored and synced to the output.

-
-
--no-delete
-
-

Don’t delete the "vendor" directory when vendoring, but rather keep all -existing contents of the vendor directory

-
-
--respect-source-config
-
-

Instead of ignoring [source] configuration by default in .cargo/config.toml -read it and use it when downloading crates from crates.io, for example

-
-
--versioned-dirs
-
-

Normally versions are only added to disambiguate multiple versions of the -same package. This option causes all directories in the "vendor" directory -to be versioned, which makes it easier to track the history of vendored -packages over time, and can help with the performance of re-vendoring when -only a subset of the packages have changed.

-
-
-
-
-
-

Manifest Options

-
-
-
--manifest-path PATH
-
-

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

-
-
-
-
-
-

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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-
-
-

ENVIRONMENT

-
-
-

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

-
-
-
-
-

Exit Status

-
-
-
-
0
-
-

Cargo succeeded.

-
-
101
-
-

Cargo failed to complete.

-
-
-
-
-
-
-

EXAMPLES

-
-
-
    -
  1. -

    Vendor all dependencies into a local "vendor" folder

    -
    -
    -
    cargo vendor
    -
    -
    -
    2. -
  2. -

    Vendor all dependencies into a local "third-party/vendor" folder

    -
    -
    -
    cargo vendor third-party/vendor
    -
    -
    -
    3. -
  3. -

    Vendor the current workspace as well as another to "vendor"

    -
    -
    -
    cargo vendor -s ../path/to/Cargo.toml
    -
    -
    -
    4. -
-
-
-
-
-

SEE ALSO

-
-
-

cargo(1)

-
-
-
\ No newline at end of file diff --git a/src/doc/man/generated/cargo-verify-project.html b/src/doc/man/generated/cargo-verify-project.html deleted file mode 100644 index 8eabe22cead..00000000000 --- a/src/doc/man/generated/cargo-verify-project.html +++ /dev/null @@ -1,199 +0,0 @@ -

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 for the -Cargo.toml file in the current directory or any parent directory.

-
-
--frozen
-
--locked
-
-

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

-
-

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

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo-version.html b/src/doc/man/generated/cargo-version.html deleted file mode 100644 index 2c84a33d0c6..00000000000 --- a/src/doc/man/generated/cargo-version.html +++ /dev/null @@ -1,76 +0,0 @@ -

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/man/generated/cargo-yank.html b/src/doc/man/generated/cargo-yank.html deleted file mode 100644 index 5a899f9e187..00000000000 --- a/src/doc/man/generated/cargo-yank.html +++ /dev/null @@ -1,196 +0,0 @@ -

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

-
-
-

Yank 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. This overrides the token stored in -the credentials file (which is created by cargo-login(1)).

-
-

Cargo config environment variables can be -used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the CARGO_REGISTRY_TOKEN environment -variable. Tokens for other registries may be specified with environment -variables of the form CARGO_REGISTRIES_NAME_TOKEN where NAME is the name -of the registry in all capital letters.

-
-
-
--index INDEX
-
-

The URL of the registry index to use.

-
-
--registry REGISTRY
-
-

Name of the registry to use. Registry names are defined in Cargo config files. -If not specified, the default registry is used, which is defined by the -registry.default config key which defaults to crates-io.

-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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/man/generated/cargo.html b/src/doc/man/generated/cargo.html deleted file mode 100644 index 3c13db331aa..00000000000 --- a/src/doc/man/generated/cargo.html +++ /dev/null @@ -1,470 +0,0 @@ -

NAME

-
-

cargo - The Rust package manager

-
-
-

SYNOPSIS

-
-
-

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

-
-
-
-
-

DESCRIPTION

-
-
-

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

-
-
-
-
-

COMMANDS

-
-
-

Build Commands

-
-
-
cargo-bench(1)
-
-

Execute benchmarks of a package.

-
-
cargo-build(1)
-
-

Compile a package.

-
-
cargo-check(1)
-
-

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

-
-
cargo-clean(1)
-
-

Remove artifacts that Cargo has generated in the past.

-
-
cargo-doc(1)
-
-

Build a package’s documentation.

-
-
cargo-fetch(1)
-
-

Fetch dependencies of a package from the network.

-
-
cargo-fix(1)
-
-

Automatically fix lint warnings reported by rustc.

-
-
cargo-run(1)
-
-

Run a binary or example of the local package.

-
-
cargo-rustc(1)
-
-

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

-
-
cargo-rustdoc(1)
-
-

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

-
-
cargo-test(1)
-
-

Execute unit and integration tests of a package.

-
-
-
-
-
-

Manifest Commands

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

Generate Cargo.lock for a project.

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

Print a JSON representation of a Cargo.toml file’s location.

-
-
cargo-metadata(1)
-
-

Output the resolved dependencies of a package, the concrete used versions -including overrides, in machine-readable format.

-
-
cargo-pkgid(1)
-
-

Print a fully qualified package specification.

-
-
cargo-tree(1)
-
-

Display a tree visualization of a dependency graph.

-
-
cargo-update(1)
-
-

Update dependencies as recorded in the local lock file.

-
-
cargo-vendor(1)
-
-

Vendor all dependencies locally.

-
-
cargo-verify-project(1)
-
-

Check correctness of crate manifest.

-
-
-
-
-
-

Package Commands

-
-
-
cargo-init(1)
-
-

Create a new Cargo package in an existing directory.

-
-
cargo-install(1)
-
-

Build and install a Rust binary.

-
-
cargo-new(1)
-
-

Create a new Cargo package.

-
-
cargo-search(1)
-
-

Search packages in crates.io.

-
-
cargo-uninstall(1)
-
-

Remove a Rust binary.

-
-
-
-
-
-

Publishing Commands

-
-
-
cargo-login(1)
-
-

Save an API token from the registry locally.

-
-
cargo-owner(1)
-
-

Manage the owners of a crate on the registry.

-
-
cargo-package(1)
-
-

Assemble the local package into a distributable tarball.

-
-
cargo-publish(1)
-
-

Upload a package to the registry.

-
-
cargo-yank(1)
-
-

Remove a pushed crate from the index.

-
-
-
-
-
-

General Commands

-
-
-
cargo-help(1)
-
-

Display help information about Cargo.

-
-
cargo-version(1)
-
-

Show version information.

-
-
-
-
-
-
-
-

OPTIONS

-
-
-

Special Options

-
-
-
-V
-
--version
-
-

Print version info and exit. If used with --verbose, prints extra -information.

-
-
--list
-
-

List all installed Cargo subcommands. If used with --verbose, prints -extra information.

-
-
--explain CODE
-
-

Run rustc --explain CODE which will print out a detailed explanation of -an error message (for example, E0004).

-
-
-
-
-
-

Display Options

-
-
-
-v
-
--verbose
-
-

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

-
-
-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.

-
-
-
--offline
-
-

Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible.

-
-

Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the cargo-fetch(1) command to download dependencies before going -offline.

-
-
-

May also be specified with the net.offline config value.

-
-
-
-
-
-
-

Common Options

-
-
-
+TOOLCHAIN
-
-

If Cargo has been installed with rustup, and the first argument to cargo -begins with +, it will be interpreted as a rustup toolchain name (such -as +stable or +nightly). -See the rustup documentation -for more information about how toolchain overrides work.

-
-
-h
-
--help
-
-

Prints help information.

-
-
-Z FLAG…​
-
-

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

-
-
-
-
-
-
-
-

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.toml
-
-

The global configuration file. See the reference -for more information about configuration files.

-
-
.cargo/config.toml
-
-

Cargo automatically searches for a file named .cargo/config.toml in the -current directory, and all parent directories. These configuration files -will be merged with the global configuration file.

-
-
$CARGO_HOME/credentials.toml
-
-

Private authentication information for logging in to a registry.

-
-
$CARGO_HOME/registry/
-
-

This directory contains cached downloads of the registry index and any -downloaded dependencies.

-
-
$CARGO_HOME/git/
-
-

This directory contains cached downloads of git dependencies.

-
-
-
-
-

Please note that the internal structure of the $CARGO_HOME directory is not -stable yet and may be subject to change.

-
-
-
-
-

EXAMPLES

-
-
-
    -
  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 From 2d4aa38b4f79e8e50048aba9e97d9e6cf63c5e9f Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 1 Aug 2020 09:38:02 -0700 Subject: [PATCH 5/7] Regenerate man pages using mdman. --- src/doc/man/generated_txt/cargo-bench.txt | 347 +++++++++++ src/doc/man/generated_txt/cargo-build.txt | 308 ++++++++++ src/doc/man/generated_txt/cargo-check.txt | 300 ++++++++++ src/doc/man/generated_txt/cargo-clean.txt | 145 +++++ src/doc/man/generated_txt/cargo-doc.txt | 266 +++++++++ src/doc/man/generated_txt/cargo-fetch.txt | 128 ++++ src/doc/man/generated_txt/cargo-fix.txt | 354 ++++++++++++ .../generated_txt/cargo-generate-lockfile.txt | 104 ++++ src/doc/man/generated_txt/cargo-help.txt | 23 + src/doc/man/generated_txt/cargo-init.txt | 150 +++++ src/doc/man/generated_txt/cargo-install.txt | 298 ++++++++++ .../generated_txt/cargo-locate-project.txt | 78 +++ src/doc/man/generated_txt/cargo-login.txt | 87 +++ src/doc/man/generated_txt/cargo-metadata.txt | 407 +++++++++++++ src/doc/man/generated_txt/cargo-new.txt | 145 +++++ src/doc/man/generated_txt/cargo-owner.txt | 122 ++++ src/doc/man/generated_txt/cargo-package.txt | 204 +++++++ src/doc/man/generated_txt/cargo-pkgid.txt | 142 +++++ src/doc/man/generated_txt/cargo-publish.txt | 205 +++++++ src/doc/man/generated_txt/cargo-run.txt | 233 ++++++++ src/doc/man/generated_txt/cargo-rustc.txt | 290 ++++++++++ src/doc/man/generated_txt/cargo-rustdoc.txt | 292 ++++++++++ src/doc/man/generated_txt/cargo-search.txt | 84 +++ src/doc/man/generated_txt/cargo-test.txt | 389 +++++++++++++ src/doc/man/generated_txt/cargo-tree.txt | 332 +++++++++++ src/doc/man/generated_txt/cargo-uninstall.txt | 96 +++ src/doc/man/generated_txt/cargo-update.txt | 137 +++++ src/doc/man/generated_txt/cargo-vendor.txt | 137 +++++ .../generated_txt/cargo-verify-project.txt | 107 ++++ src/doc/man/generated_txt/cargo-version.txt | 32 + src/doc/man/generated_txt/cargo-yank.txt | 109 ++++ src/doc/man/generated_txt/cargo.txt | 270 +++++++++ src/doc/src/commands/cargo-bench.md | 426 +++++++++++++- src/doc/src/commands/cargo-build.md | 379 +++++++++++- src/doc/src/commands/cargo-check.md | 374 +++++++++++- src/doc/src/commands/cargo-clean.md | 185 +++++- src/doc/src/commands/cargo-doc.md | 336 ++++++++++- src/doc/src/commands/cargo-fetch.md | 158 ++++- src/doc/src/commands/cargo-fix.md | 439 +++++++++++++- .../src/commands/cargo-generate-lockfile.md | 133 ++++- src/doc/src/commands/cargo-help.md | 29 +- src/doc/src/commands/cargo-init.md | 172 +++++- src/doc/src/commands/cargo-install.md | 357 +++++++++++- src/doc/src/commands/cargo-locate-project.md | 107 +++- src/doc/src/commands/cargo-login.md | 114 +++- src/doc/src/commands/cargo-metadata.md | 451 ++++++++++++++- src/doc/src/commands/cargo-new.md | 167 +++++- src/doc/src/commands/cargo-owner.md | 160 ++++- src/doc/src/commands/cargo-package.md | 254 +++++++- src/doc/src/commands/cargo-pkgid.md | 170 +++++- src/doc/src/commands/cargo-publish.md | 260 ++++++++- src/doc/src/commands/cargo-run.md | 297 +++++++++- src/doc/src/commands/cargo-rustc.md | 359 +++++++++++- src/doc/src/commands/cargo-rustdoc.md | 363 +++++++++++- src/doc/src/commands/cargo-search.md | 118 +++- src/doc/src/commands/cargo-test.md | 471 ++++++++++++++- src/doc/src/commands/cargo-tree.md | 387 ++++++++++++- src/doc/src/commands/cargo-uninstall.md | 128 +++- src/doc/src/commands/cargo-update.md | 173 +++++- src/doc/src/commands/cargo-vendor.md | 177 +++++- src/doc/src/commands/cargo-verify-project.md | 138 ++++- src/doc/src/commands/cargo-version.md | 45 +- src/doc/src/commands/cargo-yank.md | 146 ++++- src/doc/src/commands/cargo.md | 314 +++++++++- src/etc/man/cargo-bench.1 | 466 +++++---------- src/etc/man/cargo-build.1 | 405 +++++-------- src/etc/man/cargo-check.1 | 393 +++++-------- src/etc/man/cargo-clean.1 | 194 ++----- src/etc/man/cargo-doc.1 | 352 ++++------- src/etc/man/cargo-fetch.1 | 166 ++---- src/etc/man/cargo-fix.1 | 468 ++++++--------- src/etc/man/cargo-generate-lockfile.1 | 147 ++--- src/etc/man/cargo-help.1 | 61 +- src/etc/man/cargo-init.1 | 290 +++------- src/etc/man/cargo-install.1 | 426 +++++--------- src/etc/man/cargo-locate-project.1 | 135 ++--- src/etc/man/cargo-login.1 | 144 ++--- src/etc/man/cargo-metadata.1 | 200 +++---- src/etc/man/cargo-new.1 | 288 ++------- src/etc/man/cargo-owner.1 | 191 ++---- src/etc/man/cargo-package.1 | 320 +++------- src/etc/man/cargo-pkgid.1 | 229 +++----- src/etc/man/cargo-publish.1 | 274 +++------ src/etc/man/cargo-run.1 | 338 ++++------- src/etc/man/cargo-rustc.1 | 388 ++++--------- src/etc/man/cargo-rustdoc.1 | 380 ++++-------- src/etc/man/cargo-search.1 | 141 ++--- src/etc/man/cargo-test.1 | 546 ++++++------------ src/etc/man/cargo-tree.1 | 512 +++++----------- src/etc/man/cargo-uninstall.1 | 184 ++---- src/etc/man/cargo-update.1 | 202 +++---- src/etc/man/cargo-vendor.1 | 236 +++----- src/etc/man/cargo-verify-project.1 | 151 ++--- src/etc/man/cargo-version.1 | 77 +-- src/etc/man/cargo-yank.1 | 158 ++--- src/etc/man/cargo.1 | 527 ++++++----------- 96 files changed, 16836 insertions(+), 6261 deletions(-) create mode 100644 src/doc/man/generated_txt/cargo-bench.txt create mode 100644 src/doc/man/generated_txt/cargo-build.txt create mode 100644 src/doc/man/generated_txt/cargo-check.txt create mode 100644 src/doc/man/generated_txt/cargo-clean.txt create mode 100644 src/doc/man/generated_txt/cargo-doc.txt create mode 100644 src/doc/man/generated_txt/cargo-fetch.txt create mode 100644 src/doc/man/generated_txt/cargo-fix.txt create mode 100644 src/doc/man/generated_txt/cargo-generate-lockfile.txt create mode 100644 src/doc/man/generated_txt/cargo-help.txt create mode 100644 src/doc/man/generated_txt/cargo-init.txt create mode 100644 src/doc/man/generated_txt/cargo-install.txt create mode 100644 src/doc/man/generated_txt/cargo-locate-project.txt create mode 100644 src/doc/man/generated_txt/cargo-login.txt create mode 100644 src/doc/man/generated_txt/cargo-metadata.txt create mode 100644 src/doc/man/generated_txt/cargo-new.txt create mode 100644 src/doc/man/generated_txt/cargo-owner.txt create mode 100644 src/doc/man/generated_txt/cargo-package.txt create mode 100644 src/doc/man/generated_txt/cargo-pkgid.txt create mode 100644 src/doc/man/generated_txt/cargo-publish.txt create mode 100644 src/doc/man/generated_txt/cargo-run.txt create mode 100644 src/doc/man/generated_txt/cargo-rustc.txt create mode 100644 src/doc/man/generated_txt/cargo-rustdoc.txt create mode 100644 src/doc/man/generated_txt/cargo-search.txt create mode 100644 src/doc/man/generated_txt/cargo-test.txt create mode 100644 src/doc/man/generated_txt/cargo-tree.txt create mode 100644 src/doc/man/generated_txt/cargo-uninstall.txt create mode 100644 src/doc/man/generated_txt/cargo-update.txt create mode 100644 src/doc/man/generated_txt/cargo-vendor.txt create mode 100644 src/doc/man/generated_txt/cargo-verify-project.txt create mode 100644 src/doc/man/generated_txt/cargo-version.txt create mode 100644 src/doc/man/generated_txt/cargo-yank.txt create mode 100644 src/doc/man/generated_txt/cargo.txt diff --git a/src/doc/man/generated_txt/cargo-bench.txt b/src/doc/man/generated_txt/cargo-bench.txt new file mode 100644 index 00000000000..13b4cc6ab6f --- /dev/null +++ b/src/doc/man/generated_txt/cargo-bench.txt @@ -0,0 +1,347 @@ +CARGO-BENCH(1) + +NAME + cargo-bench - Execute benchmarks of a package + +SYNOPSIS + cargo bench [options] [benchname] [-- bench-options] + +DESCRIPTION + Compile and execute benchmarks. + + The benchmark filtering argument benchname and all the arguments + following the two dashes (--) are passed to the benchmark binaries and + thus to libtest (rustc's built in unit-test and micro-benchmarking + framework). If you are passing arguments to both Cargo and the binary, + the ones after -- go to the binary, the ones before go to Cargo. For + details about libtest's arguments see the output of cargo bench -- + --help. As an example, this will run only the benchmark named foo (and + skip other similarly named benchmarks like foobar): + + cargo bench -- foo --exact + + Benchmarks are built with the --test option to rustc which creates an + executable with a main function that automatically runs all functions + annotated with the #[bench] attribute. Cargo passes the --bench flag to + the test harness to tell it to run only benchmarks. + + The libtest harness may be disabled by setting harness = false in the + target manifest settings, in which case your code will need to provide + its own main function to handle running benchmarks. + + Note: The #[bench] attribute + + is currently unstable and only available on the nightly channel + . There + are some packages available on crates.io + that may help with running + benchmarks on the stable channel, such as Criterion + . + +OPTIONS + Benchmark Options + --no-run + Compile, but don't run benchmarks. + + --no-fail-fast + Run all benchmarks regardless of failure. Without this flag, Cargo + will exit after the first executable fails. The Rust test harness + will run all benchmarks within the executable to completion, this + flag only applies to the executable as a whole. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec..., --package spec... + Benchmark only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times. + + --workspace + Benchmark all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + Target Selection + When no target selection options are given, cargo bench will build the + following targets of the selected packages: + + o lib — used to link with binaries and benchmarks + + o bins (only if benchmark targets are built and required features are + available) + + o lib as a benchmark + + o bins as benchmarks + + o benchmark targets + + The default behavior can be changed by setting the bench flag for the + target in the manifest settings. Setting examples to bench = true will + build and run the example as a benchmark. Setting targets to bench = + false will stop them from being benchmarked by default. Target selection + options that take a target by name ignore the bench flag and will always + benchmark the given target. + + 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 targets in test mode that have the test = true + manifest flag set. By default this includes the library and binaries + built as unittests, and integration tests. Be aware that this will + also build any required dependencies, so the lib target may be built + twice (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name... + Benchmark the specified benchmark. This flag may be specified + multiple times. + + --benches + Benchmark all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Benchmark all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Benchmark for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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 + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build and execute all the benchmarks of the current package: + + cargo bench + + 2. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +SEE ALSO + cargo(1), cargo-test(1) + diff --git a/src/doc/man/generated_txt/cargo-build.txt b/src/doc/man/generated_txt/cargo-build.txt new file mode 100644 index 00000000000..2d2dd17eadd --- /dev/null +++ b/src/doc/man/generated_txt/cargo-build.txt @@ -0,0 +1,308 @@ +CARGO-BUILD(1) + +NAME + cargo-build - Compile the current package + +SYNOPSIS + cargo build [options] + +DESCRIPTION + Compile local packages and all of their dependencies. + +OPTIONS + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec..., --package spec... + Build only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Build all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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 targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name... + Build the specified benchmark. This flag may be specified multiple + times. + + --benches + Build all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Build optimized artifacts with the release profile. 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. See + https://github.com/rust-lang/cargo/issues/6790 for more information. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + --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. See + for more + information. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package and all of its dependencies: + + cargo build + + 2. Build with optimizations: + + cargo build --release + +SEE ALSO + cargo(1), cargo-rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-check.txt b/src/doc/man/generated_txt/cargo-check.txt new file mode 100644 index 00000000000..a2751713076 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-check.txt @@ -0,0 +1,300 @@ +CARGO-CHECK(1) + +NAME + cargo-check - Check the current package + +SYNOPSIS + cargo check [options] + +DESCRIPTION + Check a local package and all of its dependencies for errors. This will + essentially compile the packages without performing the final step of + code generation, which is faster than running cargo build. The compiler + will save metadata files to disk so that future runs will reuse them if + the source has not been modified. + +OPTIONS + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec..., --package spec... + Check only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Check all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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 targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name... + Check the specified benchmark. This flag may be specified multiple + times. + + --benches + Check all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Check all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Check for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Check optimized artifacts with the release profile. 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Check the local package for errors: + + cargo check + + 2. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-clean.txt b/src/doc/man/generated_txt/cargo-clean.txt new file mode 100644 index 00000000000..4a55ae00736 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-clean.txt @@ -0,0 +1,145 @@ +CARGO-CLEAN(1) + +NAME + cargo-clean - Remove generated artifacts + +SYNOPSIS + cargo clean [options] + +DESCRIPTION + Remove artifacts from the target directory that Cargo has generated in + the past. + + With no options, cargo clean will delete the entire target directory. + +OPTIONS + Package Selection + When no packages are selected, all packages and all dependencies in the + workspace are cleaned. + + -p spec..., --package spec... + Clean only the specified packages. This flag may be specified + multiple times. See cargo-pkgid(1) for the SPEC format. + + Clean Options + --doc + This option will cause cargo clean to remove only the doc directory + in the target directory. + + --release + 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 + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Remove the entire target directory: + + cargo clean + + 2. Remove only the release artifacts: + + cargo clean --release + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-doc.txt b/src/doc/man/generated_txt/cargo-doc.txt new file mode 100644 index 00000000000..536fcbf927b --- /dev/null +++ b/src/doc/man/generated_txt/cargo-doc.txt @@ -0,0 +1,266 @@ +CARGO-DOC(1) + +NAME + cargo-doc - Build a package's documentation + +SYNOPSIS + cargo doc [options] + +DESCRIPTION + Build the documentation for the local package and all dependencies. The + output is placed in target/doc in rustdoc's usual format. + +OPTIONS + Documentation Options + --open + Open the docs in a browser after building them. This will use your + default browser unless you define another one in the BROWSER + environment variable. + + --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 selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec..., --package spec... + Document only the specified packages. See cargo-pkgid(1) for the + SPEC format. This flag may be specified multiple times. + + --workspace + Document all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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 + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Document optimized artifacts with the release profile. 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package documentation and its dependencies and output + to target/doc. + + cargo doc + +SEE ALSO + cargo(1), cargo-rustdoc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-fetch.txt b/src/doc/man/generated_txt/cargo-fetch.txt new file mode 100644 index 00000000000..5deccaf1855 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fetch.txt @@ -0,0 +1,128 @@ +CARGO-FETCH(1) + +NAME + cargo-fetch - Fetch dependencies of a package from the network + +SYNOPSIS + cargo fetch [options] + +DESCRIPTION + If a Cargo.lock file is available, this command will ensure that all of + the git dependencies and/or registry dependencies are downloaded and + locally available. Subsequent Cargo commands never touch the network + after a cargo fetch unless the lock file changes. + + If the lock file is not available, then this command will generate the + lock file before fetching the dependencies. + + If --target is not specified, then all target dependencies are fetched. + + See also the cargo-prefetch + plugin which adds a command to download popular crates. This may be + useful if you plan to use Cargo without a network with the --offline + flag. + +OPTIONS + Fetch options + --target triple + Fetch for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Fetch all dependencies: + + cargo fetch + +SEE ALSO + cargo(1), cargo-update(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-fix.txt b/src/doc/man/generated_txt/cargo-fix.txt new file mode 100644 index 00000000000..b63933eec06 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-fix.txt @@ -0,0 +1,354 @@ +CARGO-FIX(1) + +NAME + cargo-fix - Automatically fix lint warnings reported by rustc + +SYNOPSIS + cargo fix [options] + +DESCRIPTION + This Cargo subcommand will automatically take rustc's suggestions from + diagnostics like warnings and apply them to your source code. This is + intended to help automate tasks that rustc itself already knows how to + tell you to fix! 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. + + cargo fix is only capable of fixing code that is normally compiled with + cargo check. If code is conditionally enabled with optional features, + you will need to enable those features for that code to be analyzed: + + cargo fix --edition --features foo + + Similarly, other cfg expressions like platform-specific code will need + to pass --target to fix code for the given target. + + cargo fix --edition --target x86_64-pc-windows-gnu + + If you encounter any problems with cargo fix or otherwise have any + questions or feature requests please don't hesitate to file an issue at + + +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 selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec..., --package spec... + Fix only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Fix all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + 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 targets in test mode that have the test = true manifest flag + set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name... + Fix the specified benchmark. This flag may be specified multiple + times. + + --benches + Fix all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Fix all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Fix for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Fix optimized artifacts with the release profile. 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Apply compiler suggestions to the local package: + + cargo fix + + 2. Convert a 2015 edition to 2018: + + cargo fix --edition + + 3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +SEE ALSO + cargo(1), cargo-check(1) + diff --git a/src/doc/man/generated_txt/cargo-generate-lockfile.txt b/src/doc/man/generated_txt/cargo-generate-lockfile.txt new file mode 100644 index 00000000000..5ef41c05dec --- /dev/null +++ b/src/doc/man/generated_txt/cargo-generate-lockfile.txt @@ -0,0 +1,104 @@ +CARGO-GENERATE-LOCKFILE(1) + +NAME + cargo-generate-lockfile - Generate the lockfile for a package + +SYNOPSIS + cargo generate-lockfile [options] + +DESCRIPTION + This command will create the Cargo.lock lockfile for the current package + or workspace. If the lockfile already exists, it will be rebuilt 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create or update the lockfile for the current package or workspace: + + cargo generate-lockfile + +SEE ALSO + cargo(1), cargo-update(1) + diff --git a/src/doc/man/generated_txt/cargo-help.txt b/src/doc/man/generated_txt/cargo-help.txt new file mode 100644 index 00000000000..ea87ddfdb48 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-help.txt @@ -0,0 +1,23 @@ +CARGO-HELP(1) + +NAME + cargo-help - Get help for a Cargo command + +SYNOPSIS + cargo help [subcommand] + +DESCRIPTION + Prints a help message for the given command. + +EXAMPLES + 1. Get help for a command: + + cargo help build + + 2. Help is also available with the --help flag: + + cargo build --help + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-init.txt b/src/doc/man/generated_txt/cargo-init.txt new file mode 100644 index 00000000000..9ef78f94280 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-init.txt @@ -0,0 +1,150 @@ +CARGO-INIT(1) + +NAME + cargo-init - Create a new Cargo package in an existing directory + +SYNOPSIS + cargo init [options] [path] + +DESCRIPTION + This command will create a new Cargo manifest in the current directory. + Give a path as an argument to create in the given directory. + + If there are typically-named Rust source files already in the directory, + those will be used. If not, then a sample src/main.rs file will be + created, or src/lib.rs if --lib is passed. + + If the directory is not already in a VCS repository, then a new + repository is created (see --vcs below). + + 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): + + o cargo-new.name Cargo config value + + o CARGO_NAME environment variable + + o GIT_AUTHOR_NAME environment variable + + o GIT_COMMITTER_NAME environment variable + + o user.name git configuration value + + o USER environment variable + + o USERNAME environment variable + + o NAME environment variable + + The email address is optional and is determined from: + + o cargo-new.email Cargo config value + + o CARGO_EMAIL environment variable + + o GIT_AUTHOR_EMAIL environment variable + + o GIT_COMMITTER_EMAIL environment variable + + o user.email git configuration value + + o 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 + This sets the publish field in Cargo.toml to the given registry name + which will restrict publishing only to that registry. + + Registry names are defined in Cargo config files + . If not + specified, the default registry defined by the registry.default + config key is used. If the default registry is not set and + --registry is not used, the publish field will not be set which + means that publishing will not be restricted. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the current directory: + + cargo init + +SEE ALSO + cargo(1), cargo-new(1) + diff --git a/src/doc/man/generated_txt/cargo-install.txt b/src/doc/man/generated_txt/cargo-install.txt new file mode 100644 index 00000000000..f02a8b23ece --- /dev/null +++ b/src/doc/man/generated_txt/cargo-install.txt @@ -0,0 +1,298 @@ +CARGO-INSTALL(1) + +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 executable [[bin]] or [[example]] targets can be + installed, and all executables are installed into the installation + root's bin folder. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + + + o CARGO_HOME environment variable + + o $HOME/.cargo + + There are multiple sources from which a crate can be installed. The + default location is crates.io but the --git, --path, and --registry + flags can change this source. If the source contains more than one + package (such as crates.io or a git repository with multiple crates) the + crate argument is required to indicate which crate should be installed. + + Crates from crates.io can optionally specify the version they wish to + install via the --version flags, and similarly packages from git + repositories can optionally specify the branch, tag, or revision that + should be installed. If a crate has multiple binaries, the --bin + argument can selectively install only one of them, and if you'd rather + install examples the --example argument can be used as well. + + If the package is already installed, Cargo will reinstall it if the + installed version does not appear to be up-to-date. If any of the + following values change, then Cargo will reinstall the package: + + o The package version and source. + + o The set of binary names installed. + + o The chosen features. + + o The release mode (--debug). + + o The target (--target). + + Installing with --path will always build and install, unless there are + conflicting binaries from another package. The --force flag may be used + to force Cargo to always reinstall the package. + + If the source is crates.io or --git then by default the crate will be + built in a temporary target directory. To avoid this, the target + directory can be specified by setting the CARGO_TARGET_DIR environment + variable to a relative path. In particular, this can be useful for + caching build artifacts on continuous integration systems. + + By default, the Cargo.lock file that is included with the package will + be ignored. This means that Cargo will recompute which versions of + dependencies to use, possibly using newer versions that have been + released since the package was published. The --locked flag can be used + to force Cargo to use the packaged Cargo.lock file if it is available. + This may be useful for ensuring reproducible builds, to use the exact + same set of dependencies that were available when the package was + published. It may also be useful if a newer version of a dependency is + published that no longer builds on your system, or has other problems. + The downside to using --locked is that you will not receive any fixes or + updates to any dependency. Note that Cargo did not start publishing + Cargo.lock files until version 1.37, which means packages published with + prior versions will not have a Cargo.lock file available. + +OPTIONS + Install Options + --vers version, --version version + Specify a version to install. This may be a version requirement + , + like ~1.2, to have Cargo select the newest version from the given + requirement. If the version does not have a requirement operator + (such as ^ or ~), then it must be in the form MAJOR.MINOR.PATCH, and + will install exactly that version; it is not treated as a caret + requirement like Cargo dependencies are. + + --git url + Git URL to install the specified crate from. + + --branch branch + Branch to use when installing from git. + + --tag tag + Tag to use when installing from git. + + --rev sha + Specific commit to use when installing from git. + + --path path + Filesystem path to local crate to install. + + --list + List all installed packages and their versions. + + -f, --force + Force overwriting existing crates or binaries. This can be used if a + package has installed a binary with the same name as another + package. This is also useful if something has changed on the system + that you want to rebuild with, such as a newer version of rustc. + + --no-track + By default, Cargo keeps track of the installed packages with a + metadata file stored in the installation root directory. This flag + tells Cargo not to use or create that file. With this flag, Cargo + will refuse to overwrite any existing files unless the --force flag + is used. This also disables Cargo's ability to protect against + multiple concurrent invocations of Cargo installing at the same + time. + + --bin name... + Install only the specified binary. + + --bins + Install all binaries. + + --example name... + Install only the specified example. + + --examples + Install all examples. + + --root dir + Directory to install packages into. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + . If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + --index index + The URL of the registry index to use. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Install for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + . Defaults to + target in the root of the workspace. + + --debug + Build with the dev profile instead the release profile. + + Manifest Options + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Install or upgrade a package from crates.io: + + cargo install ripgrep + + 2. Install or reinstall the package in the current directory: + + cargo install --path . + + 3. View the list of installed packages: + + cargo install --list + +SEE ALSO + cargo(1), cargo-uninstall(1), cargo-search(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-locate-project.txt b/src/doc/man/generated_txt/cargo-locate-project.txt new file mode 100644 index 00000000000..ec1377fb568 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-locate-project.txt @@ -0,0 +1,78 @@ +CARGO-LOCATE-PROJECT(1) + +NAME + cargo-locate-project - Print a JSON representation of a Cargo.toml + file's location + +SYNOPSIS + cargo locate-project [options] + +DESCRIPTION + This command will print a JSON object to stdout with the full path to + the 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the path to the manifest based on the current directory: + + cargo locate-project + +SEE ALSO + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-login.txt b/src/doc/man/generated_txt/cargo-login.txt new file mode 100644 index 00000000000..447c32c002f --- /dev/null +++ b/src/doc/man/generated_txt/cargo-login.txt @@ -0,0 +1,87 @@ +CARGO-LOGIN(1) + +NAME + cargo-login - Save an API token from the registry locally + +SYNOPSIS + cargo login [options] [token] + +DESCRIPTION + This command will save the API token to disk so that commands that + require authentication, such as cargo-publish(1), will be automatically + authenticated. The token is saved in $CARGO_HOME/credentials.toml. + CARGO_HOME defaults to .cargo in your home directory. + + If the token argument is not specified, it will be read from stdin. + + The API token for crates.io may be retrieved from + . + + Take care to keep the token secret, it should not be shared with anyone + else. + +OPTIONS + Login Options + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + . If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Save the API token to disk: + + cargo login + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-metadata.txt b/src/doc/man/generated_txt/cargo-metadata.txt new file mode 100644 index 00000000000..5ecd04f4445 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-metadata.txt @@ -0,0 +1,407 @@ +CARGO-METADATA(1) + +:source-highlighter: highlightjs + +NAME + cargo-metadata - Machine-readable metadata about the current package + +SYNOPSIS + cargo metadata [options] + +DESCRIPTION + Output JSON to stdout containing information about the workspace members + and resolved dependencies of the current package. + + It is recommended to include the --format-version flag to future-proof + your code to ensure the output is in the format you are expecting. + + See the 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. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* A string of the URL of the registry this dependency is from. + If not specified or null, the dependency is from the default + registry (crates.io). + */ + "registry": null + } + ], + /* Array of Cargo targets. */ + "targets": [ + { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "bin" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "bin" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/main.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": false, + /* Whether or not this target should be built and run with `--test` + */ + "test": true + } + ], + /* Set of features defined for the package. + Each feature maps to an array of features or dependencies it + enables. + */ + "features": { + "default": [ + "feat1" + ], + "feat1": [], + "feat2": [] + }, + /* Absolute path to this package's manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* Package metadata. + This is null if no metadata is specified. + */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + }, + /* List of registries to which this package may be published. + Publishing is unrestricted if null, and forbidden if an empty array. */ + "publish": [ + "crates-io" + ], + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe " + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018", + /* Optional string that is the name of a native library the package + is linking to. + */ + "links": null, + } + ], + /* Array of members of the workspace. + Each entry is the Package ID for the package. + */ + "workspace_members": [ + "my-package 0.1.0 (path+file:///path/to/my-package)", + ], + // The resolved dependency graph for the entire workspace. The enabled + // features are based on the enabled features for the "current" package. + // Inactivated optional dependencies are not listed. + // + // This is null if --no-deps is specified. + // + // By default, this includes all dependencies for all target platforms. + // The `--filter-platform` flag may be used to narrow to a specific + // target triple. + "resolve": { + /* Array of nodes within the dependency graph. + Each node is a package. + */ + "nodes": [ + { + /* The Package ID of this node. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The dependencies of this package, an array of Package IDs. */ + "dependencies": [ + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" + ], + /* The dependencies of this package. This is an alternative to + "dependencies" which contains additional information. In + particular, this handles renamed dependencies. + */ + "deps": [ + { + /* The name of the dependency's library target. + If this is a renamed dependency, this is the new + name. + */ + "name": "bitflags", + /* The Package ID of the dependency. */ + "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + /* Array of dependency kinds. Added in Cargo 1.40. */ + "dep_kinds": [ + { + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)" + } + ] + } + ], + /* Array of features enabled on this package. */ + "features": [ + "default" + ] + } + ], + /* The root package of the workspace. + This is null if this is a virtual workspace. Otherwise it is + the Package ID of the root package. + */ + "root": "my-package 0.1.0 (path+file:///path/to/my-package)" + }, + /* The absolute path to the build directory where Cargo places its output. */ + "target_directory": "/path/to/my-package/target", + /* The version of the schema for this metadata structure. + This will be changed if incompatible changes are ever made. + */ + "version": 1, + /* The absolute path to the root of the workspace. */ + "workspace_root": "/path/to/my-package" + /* Workspace metadata. + This is null if no metadata is specified. */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + } + } + +OPTIONS + Output Options + --no-deps + Output information only about the workspace members and don't fetch + dependencies. + + --format-version version + Specify the version of the output format to use. Currently 1 is the + only possible value. + + --filter-platform triple + This filters the resolve output to only include dependencies for the + given target triple. Without this flag, the resolve includes all + targets. + + Note that the dependencies listed in the "packages" array still + includes all dependencies. Each package definition is intended to be + an unaltered reproduction of the information within Cargo.toml. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Output JSON about the current package: + + cargo metadata --format-version=1 + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-new.txt b/src/doc/man/generated_txt/cargo-new.txt new file mode 100644 index 00000000000..241db365829 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-new.txt @@ -0,0 +1,145 @@ +CARGO-NEW(1) + +NAME + cargo-new - Create a new Cargo package + +SYNOPSIS + cargo new [options] path + +DESCRIPTION + This command will create a new Cargo package in the given directory. + This includes a simple template with a Cargo.toml manifest, sample + source file, and a VCS ignore file. If the directory is not already in a + VCS repository, then a new repository is created (see --vcs below). + + 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): + + o cargo-new.name Cargo config value + + o CARGO_NAME environment variable + + o GIT_AUTHOR_NAME environment variable + + o GIT_COMMITTER_NAME environment variable + + o user.name git configuration value + + o USER environment variable + + o USERNAME environment variable + + o NAME environment variable + + The email address is optional and is determined from: + + o cargo-new.email Cargo config value + + o CARGO_EMAIL environment variable + + o GIT_AUTHOR_EMAIL environment variable + + o GIT_COMMITTER_EMAIL environment variable + + o user.email git configuration value + + o 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 + This sets the publish field in Cargo.toml to the given registry name + which will restrict publishing only to that registry. + + Registry names are defined in Cargo config files + . If not + specified, the default registry defined by the registry.default + config key is used. If the default registry is not set and + --registry is not used, the publish field will not be set which + means that publishing will not be restricted. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a binary Cargo package in the given directory: + + cargo new foo + +SEE ALSO + cargo(1), cargo-init(1) + diff --git a/src/doc/man/generated_txt/cargo-owner.txt b/src/doc/man/generated_txt/cargo-owner.txt new file mode 100644 index 00000000000..65128529651 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-owner.txt @@ -0,0 +1,122 @@ +CARGO-OWNER(1) + +NAME + cargo-owner - Manage the owners of a crate on the registry + +SYNOPSIS + cargo owner [options] --add login [crate] + cargo owner [options] --remove login [crate] + cargo owner [options] --list [crate] + +DESCRIPTION + This command will modify the owners for a crate on the registry. Owners + of a crate can upload new versions and yank old versions. Non-team + owners can also modify the set of owners, so take care! + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + If the crate name is not specified, it will use the package name from + the current directory. + + See the reference + + for more information about owners and publishing. + +OPTIONS + Owner Options + -a, --add login... + Invite the given user or team as an owner. + + -r, --remove login... + Remove the given user or team as an owner. + + -l, --list + List owners of a crate. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + . If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. List owners of a package: + + cargo owner --list foo + + 2. Invite an owner to a package: + + cargo owner --add username foo + + 3. Remove an owner from a package: + + cargo owner --remove username foo + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-package.txt b/src/doc/man/generated_txt/cargo-package.txt new file mode 100644 index 00000000000..2e82404c2eb --- /dev/null +++ b/src/doc/man/generated_txt/cargo-package.txt @@ -0,0 +1,204 @@ +CARGO-PACKAGE(1) + +NAME + cargo-package - Assemble the local package into a distributable tarball + +SYNOPSIS + cargo package [options] + +DESCRIPTION + This command will create a distributable, compressed .crate file with + the source code of the package in the current directory. The resulting + file will be stored in the target/package directory. This performs the + following steps: + + 1. Load and check the current workspace, performing some basic checks. + o Path dependencies are not allowed unless they have a version key. + Cargo will ignore the path key for dependencies in published + packages. dev-dependencies do not have this restriction. + + 2. Create the compressed .crate file. + o The original Cargo.toml file is rewritten and normalized. + + o [patch], [replace], and [workspace] sections are removed from the + manifest. + + o Cargo.lock is automatically included if the package contains an + executable binary or example target. cargo-install(1) will use the + packaged lock file if the --locked flag is used. + + o A .cargo_vcs_info.json file is included that contains information + about the current VCS checkout hash if available (not included + with --allow-dirty). + + 3. Extract the .crate file and build it to verify it can build. + o This will rebuild your package from scratch to ensure that it can + be built from a pristine state. The --no-verify flag can be used + to skip this step. + + 4. Check that build scripts did not modify any source files. + + The list of files included can be controlled with the include and + exclude fields in the manifest. + + See the reference + 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 + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + . Defaults to + target in the root of the workspace. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Create a compressed .crate file of the current package: + + cargo package + +SEE ALSO + cargo(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-pkgid.txt b/src/doc/man/generated_txt/cargo-pkgid.txt new file mode 100644 index 00000000000..01a910d0378 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-pkgid.txt @@ -0,0 +1,142 @@ +CARGO-PKGID(1) + +NAME + cargo-pkgid - Print a fully qualified package specification + +SYNOPSIS + cargo pkgid [options] [spec] + +DESCRIPTION + Given a spec argument, print out the fully qualified package ID + specifier for a package or dependency in the current workspace. This + command will generate an error if spec is ambiguous as to which package + it refers to in the dependency graph. If no spec is given, then the + specifier for the local package is printed. + + This command requires that a lockfile is available and dependencies have + been fetched. + + A package specifier consists of a name, version, and source URL. You are + allowed to use partial specifiers to succinctly match a specific package + as long as it matches only one package. The format of a spec can be one + of the following: + + +-----------------+--------------------------------------------------+ + | SPEC Structure | Example SPEC | + +-----------------+--------------------------------------------------+ + | name | bitflags | + +-----------------+--------------------------------------------------+ + | name:version | bitflags:1.0.4 | + +-----------------+--------------------------------------------------+ + | url | https://github.com/rust-lang/cargo | + +-----------------+--------------------------------------------------+ + | url#version | https://github.com/rust-lang/cargo#0.33.0 | + +-----------------+--------------------------------------------------+ + | url#name | | + | | https://github.com/rust-lang/crates.io-index#bitflags | + +-----------------+--------------------------------------------------+ + | | | + | url#name:version | https://github.com/rust-lang/cargo#crates-io:0.21.0 | + +-----------------+--------------------------------------------------+ + +OPTIONS + Package Selection + -p spec, --package spec + Get the package ID for the given package instead of the current + package. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Retrieve package specification for foo package: + + cargo pkgid foo + + 2. Retrieve package specification for version 1.0.0 of foo: + + cargo pkgid foo:1.0.0 + + 3. Retrieve package specification for foo from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +SEE ALSO + cargo(1), cargo-generate-lockfile(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-publish.txt b/src/doc/man/generated_txt/cargo-publish.txt new file mode 100644 index 00000000000..ed9234a984a --- /dev/null +++ b/src/doc/man/generated_txt/cargo-publish.txt @@ -0,0 +1,205 @@ +CARGO-PUBLISH(1) + +NAME + cargo-publish - Upload a package to the registry + +SYNOPSIS + cargo publish [options] + +DESCRIPTION + This command will create a distributable, compressed .crate file with + the source code of the package in the current directory and upload it to + a registry. The default registry is . This performs + the following steps: + + 1. Performs a few checks, including: + o Checks the package.publish key in the manifest for restrictions on + which registries you are allowed to publish to. + + 2. Create a .crate file by following the steps in cargo-package(1). + + 3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + + This command requires you to be authenticated with either the --token + option or using cargo-login(1). + + See the reference + for more + details about packaging and publishing. + +OPTIONS + Publish Options + --dry-run + Perform all checks without uploading. + + --token token + API token to use when authenticating. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --no-verify + Don't verify the contents by building them. + + --allow-dirty + Allow working directories with uncommitted VCS changes to be + packaged. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + . If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Compilation Options + --target triple + Publish for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --target-dir directory + Directory for all generated artifacts and intermediate files. May + also be specified with the CARGO_TARGET_DIR environment variable, or + the build.target-dir config value + . Defaults to + target in the root of the workspace. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Publish the current package: + + cargo publish + +SEE ALSO + cargo(1), cargo-package(1), cargo-login(1) + diff --git a/src/doc/man/generated_txt/cargo-run.txt b/src/doc/man/generated_txt/cargo-run.txt new file mode 100644 index 00000000000..4bb9dbf4b49 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-run.txt @@ -0,0 +1,233 @@ +CARGO-RUN(1) + +NAME + cargo-run - Run the current package + +SYNOPSIS + cargo run [options] [-- args] + +DESCRIPTION + Run a binary or example of the local package. + + All the arguments following the two dashes (--) are passed to the binary + to run. If you're passing arguments to both Cargo and the binary, the + ones after -- go to the binary, the ones before go to Cargo. + +OPTIONS + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to run. See cargo-pkgid(1) for the SPEC format. + + Target Selection + When no target selection options are given, cargo run will run the + binary target. If there are multiple binary targets, you must pass a + target flag to choose one. Or, the default-run field may be specified in + the [package] section of Cargo.toml to choose the name of the binary to + run by default. + + --bin name + Run the specified binary. + + --example name + Run the specified example. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Run for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Run optimized artifacts with the release profile. 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build the local package and run its main target (assuming only one + binary): + + cargo run + + 2. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +SEE ALSO + cargo(1), cargo-build(1) + diff --git a/src/doc/man/generated_txt/cargo-rustc.txt b/src/doc/man/generated_txt/cargo-rustc.txt new file mode 100644 index 00000000000..7061abd0fbf --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustc.txt @@ -0,0 +1,290 @@ +CARGO-RUSTC(1) + +NAME + cargo-rustc - Compile the current package, and pass extra options to the + compiler + +SYNOPSIS + cargo rustc [options] [-- args] + +DESCRIPTION + The specified target for the current package (or package specified by -p + if provided) will be compiled along with all of its dependencies. The + specified args will all be passed to the final compiler invocation, not + any of the dependencies. Note that the compiler will still + unconditionally receive arguments such as -L, --extern, and + --crate-type, and the specified args will simply be added to the + compiler invocation. + + See 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 targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name... + Build the specified benchmark. This flag may be specified multiple + times. + + --benches + Build all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Build all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Build for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Build optimized artifacts with the release profile. 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Check if your package (not including dependencies) uses unsafe code: + + cargo rustc --lib -- -D unsafe-code + + 2. Try an experimental flag on the nightly compiler, such as this which + prints the size of every type: + + cargo rustc --lib -- -Z print-type-sizes + +SEE ALSO + cargo(1), cargo-build(1), rustc(1) + diff --git a/src/doc/man/generated_txt/cargo-rustdoc.txt b/src/doc/man/generated_txt/cargo-rustdoc.txt new file mode 100644 index 00000000000..bbf63d01d64 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-rustdoc.txt @@ -0,0 +1,292 @@ +CARGO-RUSTDOC(1) + +NAME + cargo-rustdoc - Build a package's documentation, using specified custom + flags + +SYNOPSIS + cargo rustdoc [options] [-- args] + +DESCRIPTION + The specified target for the current package (or package specified by -p + if provided) will be documented with the specified args being passed to + the final rustdoc invocation. Dependencies will not be documented as + part of this command. Note that rustdoc will still unconditionally + receive arguments such as -L, --extern, and --crate-type, and the + specified args will simply be added to the rustdoc invocation. + + See 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 config value + . + +OPTIONS + Documentation Options + --open + Open the docs in a browser after building them. This will use your + default browser unless you define another one in the BROWSER + environment variable. + + Package Selection + 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 targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name... + Document the specified benchmark. This flag may be specified + multiple times. + + --benches + Document all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Document all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Document for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Document optimized artifacts with the release profile. 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + Dependencies use the dev/release profiles. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Build documentation with custom CSS included from a given file: + + cargo rustdoc --lib -- --extend-css extra.css + +SEE ALSO + cargo(1), cargo-doc(1), rustdoc(1) + diff --git a/src/doc/man/generated_txt/cargo-search.txt b/src/doc/man/generated_txt/cargo-search.txt new file mode 100644 index 00000000000..eb3446dfb43 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-search.txt @@ -0,0 +1,84 @@ +CARGO-SEARCH(1) + +NAME + cargo-search - Search packages in crates.io + +SYNOPSIS + cargo search [options] [query...] + +DESCRIPTION + This performs a textual search for crates on . The + matching crates will be displayed along with their description in TOML + format suitable for copying into a Cargo.toml manifest. + +OPTIONS + Search Options + --limit limit + Limit the number of results (default: 10, max: 100). + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + . If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Search for a package from crates.io: + + cargo search serde + +SEE ALSO + cargo(1), cargo-install(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo-test.txt b/src/doc/man/generated_txt/cargo-test.txt new file mode 100644 index 00000000000..ad6ac27b98e --- /dev/null +++ b/src/doc/man/generated_txt/cargo-test.txt @@ -0,0 +1,389 @@ +CARGO-TEST(1) + +NAME + cargo-test - Execute unit and integration tests of a package + +SYNOPSIS + cargo test [options] [testname] [-- test-options] + +DESCRIPTION + Compile and execute unit and integration tests. + + The test filtering argument TESTNAME and all the arguments following the + two dashes (--) are passed to the test binaries and thus to libtest + (rustc's built in unit-test and micro-benchmarking framework). If you're + passing arguments to both Cargo and the binary, the ones after -- go to + the binary, the ones before go to Cargo. For details about libtest's + arguments see the output of cargo test -- --help. + + As an example, this will filter for tests with foo in their name and run + them on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + + Tests are built with the --test option to rustc which creates an + executable with a main function that automatically runs all functions + annotated with the #[test] attribute in multiple threads. #[bench] + annotated functions will also be run with one iteration to verify that + they are functional. + + The libtest harness may be disabled by setting harness = false in the + target manifest settings, in which case your code will need to provide + its own main function to handle running tests. + + Documentation tests are also run by default, which is handled by + rustdoc. It extracts code samples from documentation comments and + executes them. See the rustdoc book + for more information on writing doc tests. + +OPTIONS + Test Options + --no-run + Compile, but don't run tests. + + --no-fail-fast + Run all tests regardless of failure. Without this flag, Cargo will + exit after the first executable fails. The Rust test harness will + run all tests within the executable to completion, this flag only + applies to the executable as a whole. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec..., --package spec... + Test only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Test all members in the workspace. + + --all + Deprecated alias for --workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + Target Selection + When no target selection options are given, cargo test will build the + following targets of the selected packages: + + o lib — used to link with binaries, examples, integration tests, and + doc tests + + o bins (only if integration tests are built and required features are + available) + + o examples — to ensure they compile + + o lib as a unit test + + o bins as unit tests + + o integration tests + + o doc tests for the lib target + + The default behavior can be changed by setting the test flag for the + target in the manifest settings. Setting examples to test = true will + build and run the example as a test. Setting targets to test = false + will stop them from being tested by default. Target selection options + that take a target by name ignore the test flag and will always test the + given target. + + Doc tests for libraries may be disabled by setting doctest = false for + the library in the manifest. + + Binary targets are automatically built if there is an integration test + or benchmark. This allows an integration test to execute the binary to + exercise and test its behavior. The CARGO_bin_EXE_ environment + variable + + is set when the integration test is built so that it can use the env + macro to locate the + executable. + + 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 targets in test mode that have the test = true manifest + flag set. By default this includes the library and binaries built as + unittests, and integration tests. Be aware that this will also build + any required dependencies, so the lib target may be built twice + (once as a unittest, and once as a dependency for binaries, + integration tests, etc.). Targets may be enabled or disabled by + setting the test flag in the manifest settings for the target. + + --bench name... + Test the specified benchmark. This flag may be specified multiple + times. + + --benches + Test all targets in benchmark mode that have the bench = true + manifest flag set. By default this includes the library and binaries + built as benchmarks, and bench targets. Be aware that this will also + build any required dependencies, so the lib target may be built + twice (once as a benchmark, and once as a dependency for binaries, + benchmarks, etc.). Targets may be enabled or disabled by setting the + bench flag in the manifest settings for the target. + + --all-targets + Test all targets. This is equivalent to specifying --lib --bins + --tests --benches --examples. + + --doc + Test only the library's documentation. This cannot be mixed with + other target options. + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + Compilation Options + --target triple + Test for the given architecture. The default is the host + architecture. The general format of the triple is + ---. Run rustc --print target-list for + a list of supported targets. + + This may also be specified with the build.target config value + . + + Note that specifying this flag makes Cargo run in a different mode + where the target artifacts are placed in a separate directory. See + the build cache + + documentation for more details. + + --release + Test optimized artifacts with the release profile. 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + --message-format fmt + The output format for diagnostic messages. Can be specified multiple + times and consists of comma-separated values. Valid values: + + o human (default): Display in a human-readable text format. + + o short: Emit shorter, human-readable text messages. + + o json: Emit JSON messages to stdout. See the reference + + for more details. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + + 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. + + +----------------------------------------+-------------+--------------+ + | Target | Default | --release | + | | Profile | Profile | + +----------------------------------------+-------------+--------------+ + | lib, bin, example | dev | release | + +----------------------------------------+-------------+--------------+ + | test, bench, or any target in "test" | test | bench | + | or "bench" mode | | | + +----------------------------------------+-------------+--------------+ + + 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 + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Execute all the unit and integration tests of the current package: + + cargo test + + 2. Run only tests whose names match against a filter string: + + cargo test name_filter + + 3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +SEE ALSO + cargo(1), cargo-bench(1) + diff --git a/src/doc/man/generated_txt/cargo-tree.txt b/src/doc/man/generated_txt/cargo-tree.txt new file mode 100644 index 00000000000..d0a3828c4ed --- /dev/null +++ b/src/doc/man/generated_txt/cargo-tree.txt @@ -0,0 +1,332 @@ +CARGO-TREE(1) + +NAME + cargo-tree - Display a tree visualization of a dependency graph + +SYNOPSIS + cargo tree [options] + +DESCRIPTION + This command will display a tree of dependencies to the terminal. An + example of a simple project that depends on the "rand" package: + + myproject v0.1.0 (/myproject) + └── rand v0.7.3 + ├── getrandom v0.1.14 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── rand_core v0.5.1 (*) + [build-dependencies] + └── cc v1.0.50 + + Packages marked with (*) have been "de-duplicated". The dependencies for + the package have already been shown elswhere in the graph, and so are + not repeated. Use the --no-dedupe option to repeat the duplicates. + + The -e flag can be used to select the dependency kinds to display. The + "features" kind changes the output to display the features enabled by + each dependency. For example, cargo tree -e features: + + myproject v0.1.0 (/myproject) + └── log feature "serde" + └── log v0.4.8 + ├── serde v1.0.106 + └── cfg-if feature "default" + └── cfg-if v0.1.10 + + In this tree, myproject depends on log with the serde feature. log in + turn depends on cfg-if with "default" features. When using -e features + it can be helpful to use -i flag to show how the features flow into a + package. See the examples below for more detail. + +OPTIONS + Tree Options + -i spec, --invert spec + Show the reverse dependencies for the given package. This flag will + invert the tree and display the packages that depend on the given + package. + + Note that in a workspace, by default it will only display the + package's reverse dependencies inside the tree of the workspace + member in the current directory. The --workspace flag can be used to + extend it so that it will show the package's reverse dependencies + across the entire workspace. The -p flag can be used to display the + package's reverse dependencies only with the subtree of the package + given to -p. + + --no-dedupe + Do not de-duplicate repeated dependencies. Usually, when a package + has already displayed its dependencies, further occurrences will not + re-display its dependencies, and will include a (*) to indicate it + has already been shown. This flag will cause those duplicates to be + repeated. + + -d, --duplicates + Show only dependencies which come in multiple versions (implies + --invert). When used with the -p flag, only shows duplicates within + the subtree of the given package. + + It can be beneficial for build times and executable sizes to avoid + building that same package multiple times. This flag can help + identify the offending packages. You can then investigate if the + package that depends on the duplicate with the older version can be + updated to the newer version so that only one instance is built. + + -e kinds, --edges kinds + The dependency kinds to display. Takes a comma separated list of + values: + + o all — Show all edge kinds. + + o normal — Show normal dependencies. + + o build — Show build dependencies. + + o dev — Show development dependencies. + + o features — Show features enabled by each dependency. If this is + the only kind given, then it will automatically include the other + dependency kinds. + + o no-normal — Do not include normal dependencies. + + o no-build — Do not include build dependencies. + + o no-dev — Do not include development dependencies. + + The no- prefixed options cannot be mixed with the other dependency + kinds. + + The default is normal,build,dev. + + --target triple + Filter dependencies matching the given target-triple. The default is + the host platform. Use the value all to include all targets. + + Tree Formatting Options + --charset charset + Chooses the character set to use for the tree. Valid values are + "utf8" or "ascii". Default is "utf8". + + -f format, --format format + Set the format string for each package. The default is "{p}". + + This is an arbitrary string which will be used to display each + package. The following strings will be replaced with the + corresponding value: + + o {p} — The package name. + + o {l} — The package license. + + o {r} — The package repository URL. + + o {f} — Comma-separated list of package features that are + enabled. + + --prefix prefix + Sets how each line is displayed. The prefix value can be one of: + + o indent (default) — Shows each line indented as a tree. + + o depth — Show as a list, with the numeric depth printed before + each entry. + + o none — Show as a flat list. + + Package Selection + By default, when no package selection options are given, the packages + selected depend on the selected manifest file (based on the current + working directory if --manifest-path is not given). If the manifest is + the root of a workspace then the workspaces default members are + selected, otherwise only the package defined by the manifest will be + selected. + + The default members of a workspace can be set explicitly with the + workspace.default-members key in the root manifest. If this is not set, + a virtual workspace will include all workspace members (equivalent to + passing --workspace), and a non-virtual workspace will include only the + root crate itself. + + -p spec..., --package spec... + Display only the specified packages. See cargo-pkgid(1) for the SPEC + format. This flag may be specified multiple times. + + --workspace + Display all members in the workspace. + + --exclude SPEC... + Exclude the specified packages. Must be used in conjunction with the + --workspace flag. This flag may be specified multiple times. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Feature Selection + The feature flags allow you to control the enabled features for the + "current" package. The "current" package is the package in the current + directory, or the one specified in --manifest-path. If running in the + root of a virtual workspace, then the default features are selected for + all workspace members, or all features if --all-features is specified. + + When no feature options are given, the default feature is activated for + every selected package. + + --features features + Space or comma separated list of features to activate. These + features only apply to the current directory's package. Features of + direct dependencies may be enabled with / + syntax. This flag may be specified multiple times, which enables all + specified features. + + --all-features + Activate all available features of all selected packages. + + --no-default-features + Do not activate the default feature of the current directory's + package. + + 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Display the tree for the package in the current directory: + + cargo tree + + 2. Display all the packages that depend on the syn package: + + cargo tree -i syn + + 3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + + 4. Show all packages that are built multiple times. This can happen if + multiple semver-incompatible versions appear in the tree (like 1.0.0 + and 2.0.0). + + cargo tree -d + + 5. Explain why features are enabled for the syn package: + + cargo tree -e features -i syn + + The -e features flag is used to show features. The -i flag is used to + invert the graph so that it displays the packages that depend on syn. + An example of what this would display: + + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + + To read this graph, you can follow the chain for each feature from + the root to see why it is included. For example, the "full" feature + is added by the rustversion crate which is included from myproject + (with the default features), and myproject is the package selected on + the command-line. All of the other syn features are added by the + "default" feature ("quote" is added by "printing" and "proc-macro", + both of which are default features). + + If you're having difficulty cross-referencing the de-duplicated (*) + entries, try with the --no-dedupe flag to get the full output. + +SEE ALSO + cargo(1), cargo-metadata(1) + diff --git a/src/doc/man/generated_txt/cargo-uninstall.txt b/src/doc/man/generated_txt/cargo-uninstall.txt new file mode 100644 index 00000000000..47d4ec29f6e --- /dev/null +++ b/src/doc/man/generated_txt/cargo-uninstall.txt @@ -0,0 +1,96 @@ +CARGO-UNINSTALL(1) + +NAME + cargo-uninstall - Remove a Rust binary + +SYNOPSIS + cargo uninstall [options] [spec...] + +DESCRIPTION + This command removes a package installed with cargo-install(1). The spec + argument is a package ID specification of the package to remove (see + cargo-pkgid(1)). + + By default all binaries are removed for a crate but the --bin and + --example flags can be used to only remove particular binaries. + + The installation root is determined, in order of precedence: + + o --root option + + o CARGO_INSTALL_ROOT environment variable + + o install.root Cargo config value + + + o CARGO_HOME environment variable + + o $HOME/.cargo + +OPTIONS + Install Options + -p, --package spec... + Package to uninstall. + + --bin name... + Only uninstall the binary name. + + --root dir + Directory to uninstall packages from. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Uninstall a previously installed package. + + cargo uninstall ripgrep + +SEE ALSO + cargo(1), cargo-install(1) + diff --git a/src/doc/man/generated_txt/cargo-update.txt b/src/doc/man/generated_txt/cargo-update.txt new file mode 100644 index 00000000000..0088515fea8 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-update.txt @@ -0,0 +1,137 @@ +CARGO-UPDATE(1) + +NAME + cargo-update - Update dependencies as recorded in the local lock file + +SYNOPSIS + cargo update [options] + +DESCRIPTION + This command will update dependencies in the Cargo.lock file to the + latest version. 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). + + --dry-run + Displays what would be updated, but doesn't actually write the + lockfile. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Update all dependencies in the lockfile: + + cargo update + + 2. Update only specific dependencies: + + cargo update -p foo -p bar + + 3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +SEE ALSO + cargo(1), cargo-generate-lockfile(1) + diff --git a/src/doc/man/generated_txt/cargo-vendor.txt b/src/doc/man/generated_txt/cargo-vendor.txt new file mode 100644 index 00000000000..c5204a05433 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-vendor.txt @@ -0,0 +1,137 @@ +CARGO-VENDOR(1) + +NAME + cargo-vendor - Vendor all dependencies locally + +SYNOPSIS + cargo vendor [options] [path] + +DESCRIPTION + This cargo subcommand will vendor all crates.io and git dependencies for + a project into the specified directory at . After this command + completes the vendor directory specified by will contain all + remote sources from dependencies specified. Additional manifests beyond + the default one can be specified with the -s option. + + The cargo vendor command will also print out the configuration necessary + to use the vendored sources, which you will need to add to + .cargo/config.toml. + +OPTIONS + Vendor Options + -s manifest, --sync manifest + Specify extra Cargo.toml manifests to workspaces which should also + be vendored and synced to the output. + + --no-delete + Don't delete the "vendor" directory when vendoring, but rather keep + all existing contents of the vendor directory + + --respect-source-config + Instead of ignoring [source] configuration by default in + .cargo/config.toml read it and use it when downloading crates from + crates.io, for example + + --versioned-dirs + Normally versions are only added to disambiguate multiple versions + of the same package. This option causes all directories in the + "vendor" directory to be versioned, which makes it easier to track + the history of vendored packages over time, and can help with the + performance of re-vendoring when only a subset of the packages have + changed. + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + 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: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Vendor all dependencies into a local "vendor" folder + + cargo vendor + + 2. Vendor all dependencies into a local "third-party/vendor" folder + + cargo vendor third-party/vendor + + 3. Vendor the current workspace as well as another to "vendor" + + cargo vendor -s ../path/to/Cargo.toml + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-verify-project.txt b/src/doc/man/generated_txt/cargo-verify-project.txt new file mode 100644 index 00000000000..cfd854bfd63 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-verify-project.txt @@ -0,0 +1,107 @@ +CARGO-VERIFY-PROJECT(1) + +NAME + cargo-verify-project - Check correctness of crate manifest + +SYNOPSIS + cargo verify-project [options] + +DESCRIPTION + This command will parse the local manifest and check its validity. It + emits a JSON object with the result. A successful validation will + display: + + {"success":"true"} + + An invalid workspace will display: + + {"invalid":"human-readable error message"} + +OPTIONS + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --manifest-path path + Path to the Cargo.toml file. By default, Cargo searches for the + Cargo.toml file in the current directory or any parent directory. + + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: The workspace is OK. + + o 1: The workspace is invalid. + +EXAMPLES + 1. Check the current workspace for errors: + + cargo verify-project + +SEE ALSO + cargo(1), cargo-package(1) + diff --git a/src/doc/man/generated_txt/cargo-version.txt b/src/doc/man/generated_txt/cargo-version.txt new file mode 100644 index 00000000000..fc26df72579 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-version.txt @@ -0,0 +1,32 @@ +CARGO-VERSION(1) + +NAME + cargo-version - Show version information + +SYNOPSIS + cargo version [options] + +DESCRIPTION + Displays the version of Cargo. + +OPTIONS + -v, --verbose + Display additional version information. + +EXAMPLES + 1. Display the version: + + cargo version + + 2. The version is also available via flags: + + cargo --version + cargo -V + + 3. Display extra version information: + + cargo -Vv + +SEE ALSO + cargo(1) + diff --git a/src/doc/man/generated_txt/cargo-yank.txt b/src/doc/man/generated_txt/cargo-yank.txt new file mode 100644 index 00000000000..eff7d9391b9 --- /dev/null +++ b/src/doc/man/generated_txt/cargo-yank.txt @@ -0,0 +1,109 @@ +CARGO-YANK(1) + +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 + Yank 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. This overrides the token + stored in the credentials file (which is created by cargo-login(1)). + + Cargo config + environment variables can be used to override the tokens stored in + the credentials file. The token for crates.io may be specified with + the CARGO_REGISTRY_TOKEN environment variable. Tokens for other + registries may be specified with environment variables of the form + CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry + in all capital letters. + + --index index + The URL of the registry index to use. + + --registry registry + Name of the registry to use. Registry names are defined in Cargo + config files + . If not + specified, the default registry is used, which is defined by the + registry.default config key which defaults to crates-io. + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +EXAMPLES + 1. Yank a crate from the index: + + cargo yank --vers 1.0.7 foo + +SEE ALSO + cargo(1), cargo-login(1), cargo-publish(1) + diff --git a/src/doc/man/generated_txt/cargo.txt b/src/doc/man/generated_txt/cargo.txt new file mode 100644 index 00000000000..5925b562a8a --- /dev/null +++ b/src/doc/man/generated_txt/cargo.txt @@ -0,0 +1,270 @@ +CARGO(1) + +NAME + cargo - The Rust package manager + +SYNOPSIS + cargo [options] command [args] + cargo [options] --version + cargo [options] --list + cargo [options] --help + cargo [options] --explain code + +DESCRIPTION + This program is a package manager and build tool for the Rust language, + available at . + +COMMANDS + Build Commands + cargo-bench(1) +     Execute benchmarks of a package. + + cargo-build(1) +     Compile a package. + + cargo-check(1) +     Check a local package and all of its dependencies for errors. + + cargo-clean(1) +     Remove artifacts that Cargo has generated in the past. + + cargo-doc(1) +     Build a package's documentation. + + cargo-fetch(1) +     Fetch dependencies of a package from the network. + + cargo-fix(1) +     Automatically fix lint warnings reported by rustc. + + cargo-run(1) +     Run a binary or example of the local package. + + cargo-rustc(1) +     Compile a package, and pass extra options to the compiler. + + cargo-rustdoc(1) +     Build a package's documentation, using specified custom flags. + + cargo-test(1) +     Execute unit and integration tests of a package. + + Manifest Commands + cargo-generate-lockfile(1) +     Generate Cargo.lock for a project. + + cargo-locate-project(1) +     Print a JSON representation of a Cargo.toml file's location. + + cargo-metadata(1) +     Output the resolved dependencies of a package in + machine-readable format. + + cargo-pkgid(1) +     Print a fully qualified package specification. + + cargo-tree(1) +     Display a tree visualization of a dependency graph. + + cargo-update(1) +     Update dependencies as recorded in the local lock file. + + cargo-vendor(1) +     Vendor all dependencies locally. + + cargo-verify-project(1) +     Check correctness of crate manifest. + + Package Commands + cargo-init(1) +     Create a new Cargo package in an existing directory. + + cargo-install(1) +     Build and install a Rust binary. + + cargo-new(1) +     Create a new Cargo package. + + cargo-search(1) +     Search packages in crates.io. + + cargo-uninstall(1) +     Remove a Rust binary. + + Publishing Commands + cargo-login(1) +     Save an API token from the registry locally. + + cargo-owner(1) +     Manage the owners of a crate on the registry. + + cargo-package(1) +     Assemble the local package into a distributable tarball. + + cargo-publish(1) +     Upload a package to the registry. + + cargo-yank(1) +     Remove a pushed crate from the index. + + General Commands + cargo-help(1) +     Display help information about Cargo. + + cargo-version(1) +     Show version information. + +OPTIONS + Special Options + -V, --version + Print version info and exit. If used with --verbose, prints extra + information. + + --list + List all installed Cargo subcommands. If used with --verbose, prints + extra information. + + --explain code + Run rustc --explain CODE which will print out a detailed explanation + of an error message (for example, E0004). + + Display Options + -v, --verbose + Use verbose output. May be specified twice for "very verbose" output + which includes extra output such as dependency warnings and build + script output. May also be specified with the term.verbose config + value . + + -q, --quiet + No output printed to stdout. + + --color when + Control when colored output is used. Valid values: + + o auto (default): Automatically detect if color support is + available on the terminal. + + o always: Always display colors. + + o never: Never display colors. + + May also be specified with the term.color config value + . + + Manifest Options + --frozen, --locked + Either of these flags requires that the Cargo.lock file is + up-to-date. If the lock file is missing, or it needs to be updated, + Cargo will exit with an error. The --frozen flag also prevents Cargo + from attempting to access the network to determine if it is + out-of-date. + + These may be used in environments where you want to assert that the + Cargo.lock file is up-to-date (such as a CI build) or want to avoid + network access. + + --offline + Prevents Cargo from accessing the network for any reason. Without + this flag, Cargo will stop with an error if it needs to access the + network and the network is not available. With this flag, Cargo will + attempt to proceed without the network if possible. + + Beware that this may result in different dependency resolution than + online mode. Cargo will restrict itself to crates that are + downloaded locally, even if there might be a newer version as + indicated in the local copy of the index. See the cargo-fetch(1) + command to download dependencies before going offline. + + May also be specified with the net.offline config value + . + + Common Options + +toolchain + If Cargo has been installed with rustup, and the first argument to + cargo begins with +, it will be interpreted as a rustup toolchain + name (such as +stable or +nightly). See the rustup documentation + for more information about + how toolchain overrides work. + + -h, --help + Prints help information. + + -Z flag + Unstable (nightly-only) flags to Cargo. Run cargo -Z help for + details. + +ENVIRONMENT + See the reference + + for details on environment variables that Cargo reads. + +EXIT STATUS + o 0: Cargo succeeded. + + o 101: Cargo failed to complete. + +FILES + ~/.cargo/ +     Default location for Cargo's "home" directory where it stores + various files. The location can be changed with the CARGO_HOME + environment variable. + + $CARGO_HOME/bin/ +     Binaries installed by cargo-install(1) will be located here. If + using rustup, executables distributed with Rust are also located here. + + $CARGO_HOME/config.toml +     The global configuration file. See the reference + for more + information about configuration files. + + .cargo/config.toml +     Cargo automatically searches for a file named .cargo/config.toml + in the current directory, and all parent directories. These + configuration files will be merged with the global configuration file. + + $CARGO_HOME/credentials.toml +     Private authentication information for logging in to a registry. + + $CARGO_HOME/registry/ +     This directory contains cached downloads of the registry index + and any downloaded dependencies. + + $CARGO_HOME/git/ +     This directory contains cached downloads of git dependencies. + + Please note that the internal structure of the $CARGO_HOME directory is + not stable yet and may be subject to change. + +EXAMPLES + 1. Build a local package and all of its dependencies: + + cargo build + + 2. Build a package with optimizations: + + cargo build --release + + 3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + + 4. Create a new package that builds an executable: + + cargo new foobar + + 5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + + 6. Learn about a command's options and usage: + + cargo help clean + +BUGS + See for issues. + +SEE ALSO + rustc(1), rustdoc(1) + diff --git a/src/doc/src/commands/cargo-bench.md b/src/doc/src/commands/cargo-bench.md index e840cbf6a2d..196e0b7e8f2 100644 --- a/src/doc/src/commands/cargo-bench.md +++ b/src/doc/src/commands/cargo-bench.md @@ -1,3 +1,423 @@ -# cargo bench -{{#include command-common.html}} -{{#include ../../man/generated/cargo-bench.html}} +# cargo-bench(1) + + + +## NAME + +cargo-bench - Execute benchmarks of a package + +## SYNOPSIS + +`cargo bench` [_options_] [_benchname_] [`--` _bench-options_] + +## DESCRIPTION + +Compile and execute benchmarks. + +The benchmark filtering argument _benchname_ and all the arguments following +the two dashes (`--`) are passed to the benchmark binaries and thus to +_libtest_ (rustc's built in unit-test and micro-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after `--` go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of `cargo bench -- --help`. As an example, this will +run only the benchmark named `foo` (and skip other similarly named benchmarks +like `foobar`): + + cargo bench -- foo --exact + +Benchmarks are built with the `--test` option to `rustc` which creates an +executable with a `main` function that automatically runs all functions +annotated with the `#[bench]` attribute. Cargo passes the `--bench` flag to +the test harness to tell it to run only benchmarks. + +The libtest harness may be disabled by setting `harness = false` in the target +manifest settings, in which case your code will need to provide its own `main` +function to handle running benchmarks. + +> **Note**: The +> [`#[bench]` attribute](https://doc.rust-lang.org/nightly/unstable-book/library-features/test.html) +> is currently unstable and only available on the +> [nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html). +> There are some packages available on +> [crates.io](https://crates.io/keywords/benchmark) that may help with +> running benchmarks on the stable channel, such as +> [Criterion](https://crates.io/crates/criterion). + +## OPTIONS + +### Benchmark Options + +
+ +
--no-run
+
Compile, but don't run benchmarks.
+ + +
--no-fail-fast
+
Run all benchmarks regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all benchmarks +within the executable to completion, this flag only applies to the executable +as a whole.
+ + +
+ + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +
+ +
-p spec...
+
--package spec...
+
Benchmark only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Benchmark all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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 targets in test mode that have the test = true manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the test flag in the +manifest settings for the target.
+ + +
--bench name...
+
Benchmark the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Benchmark all targets in benchmark mode that have the bench = true +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the bench flag in the +manifest settings for the target.
+ + +
--all-targets
+
Benchmark all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
+ +### 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + + +
+ +### Manifest Options + +
+
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) +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)](cargo-build.md) 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](../reference/environment-variables.html) 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. Run only a specific benchmark within a specific benchmark target: + + cargo bench --bench bench_name -- modname::some_benchmark + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-test(1)](cargo-test.md) diff --git a/src/doc/src/commands/cargo-build.md b/src/doc/src/commands/cargo-build.md index dd46f23ed39..e65d9f22742 100644 --- a/src/doc/src/commands/cargo-build.md +++ b/src/doc/src/commands/cargo-build.md @@ -1,3 +1,376 @@ -# cargo build -{{#include command-common.html}} -{{#include ../../man/generated/cargo-build.html}} +# cargo-build(1) + + +## NAME + +cargo-build - Compile the current package + +## SYNOPSIS + +`cargo build` [_options_] + +## DESCRIPTION + +Compile local packages and all of their dependencies. + +## OPTIONS + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +
+ +
-p spec...
+
--package spec...
+
Build only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Build all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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 targets in test mode that have the test = true manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the test flag in the +manifest settings for the target.
+ + +
--bench name...
+
Build the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Build all targets in benchmark mode that have the bench = true +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the bench flag in the +manifest settings for the target.
+ + +
--all-targets
+
Build all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Build optimized artifacts with the release profile. 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. +See https://github.com/rust-lang/cargo/issues/6790 for more information.

+ + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + + +
--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. +See https://github.com/rust-lang/cargo/issues/5579 for more information.

+ +
+ +### Manifest Options + +
+
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `test` | `bench` + +Dependencies use the `dev`/`release` profiles. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. Build with optimizations: + + cargo build --release + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-rustc(1)](cargo-rustc.md) diff --git a/src/doc/src/commands/cargo-check.md b/src/doc/src/commands/cargo-check.md index 473d00afe2d..4f66e977d97 100644 --- a/src/doc/src/commands/cargo-check.md +++ b/src/doc/src/commands/cargo-check.md @@ -1,3 +1,371 @@ -# cargo check -{{#include command-common.html}} -{{#include ../../man/generated/cargo-check.html}} +# cargo-check(1) + + +## NAME + +cargo-check - Check the current package + +## SYNOPSIS + +`cargo check` [_options_] + +## DESCRIPTION + +Check a local package and all of its dependencies for errors. This will +essentially compile the packages without performing the final step of code +generation, which is faster than running `cargo build`. The compiler will save +metadata files to disk so that future runs will reuse them if the source has +not been modified. + +## OPTIONS + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +
+ +
-p spec...
+
--package spec...
+
Check only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Check all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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 targets in test mode that have the test = true manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the test flag in the +manifest settings for the target.
+ + +
--bench name...
+
Check the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Check all targets in benchmark mode that have the bench = true +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the bench flag in the +manifest settings for the target.
+ + +
--all-targets
+
Check all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Check optimized artifacts with the release profile. 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + +
+ +### Manifest Options + +
+
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `test` | `bench` + +Dependencies use the `dev`/`release` profiles. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. Check all targets, including unit tests: + + cargo check --all-targets --profile=test + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md) diff --git a/src/doc/src/commands/cargo-clean.md b/src/doc/src/commands/cargo-clean.md index df321febee8..6e0ac29f714 100644 --- a/src/doc/src/commands/cargo-clean.md +++ b/src/doc/src/commands/cargo-clean.md @@ -1,3 +1,182 @@ -# cargo clean -{{#include command-common.html}} -{{#include ../../man/generated/cargo-clean.html}} +# cargo-clean(1) + + +## NAME + +cargo-clean - Remove generated artifacts + +## SYNOPSIS + +`cargo clean` [_options_] + +## DESCRIPTION + +Remove artifacts from the target directory that Cargo has generated in the +past. + +With no options, `cargo clean` will delete the entire target directory. + +## OPTIONS + +### Package Selection + +When no packages are selected, all packages and all dependencies in the +workspace are cleaned. + +
+
-p spec...
+
--package spec...
+
Clean only the specified packages. This flag may be specified +multiple times. See cargo-pkgid(1) for the SPEC format.
+ +
+ +### Clean Options + +
+ +
--doc
+
This option will cause cargo clean to remove only the doc directory in +the target directory.
+ + +
--release
+
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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. Remove only the release artifacts: + + cargo clean --release + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md) diff --git a/src/doc/src/commands/cargo-doc.md b/src/doc/src/commands/cargo-doc.md index 9cdd897048d..02caad726a8 100644 --- a/src/doc/src/commands/cargo-doc.md +++ b/src/doc/src/commands/cargo-doc.md @@ -1,3 +1,333 @@ -# cargo doc -{{#include command-common.html}} -{{#include ../../man/generated/cargo-doc.html}} +# cargo-doc(1) + + +## NAME + +cargo-doc - Build a package's documentation + +## SYNOPSIS + +`cargo doc` [_options_] + +## DESCRIPTION + +Build the documentation for the local package and all dependencies. The output +is placed in `target/doc` in rustdoc's usual format. + +## OPTIONS + +### Documentation Options + +
+ +
--open
+
Open the docs in a browser after building them. This will use your default +browser unless you define another one in the BROWSER environment variable.
+ + +
--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 selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +
+ +
-p spec...
+
--package spec...
+
Document only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Document all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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 + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Document optimized artifacts with the release profile. 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + +
+ +### Manifest Options + +
+
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `test` | `bench` + +Dependencies use the `dev`/`release` profiles. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-rustdoc(1)](cargo-rustdoc.md), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/doc/src/commands/cargo-fetch.md b/src/doc/src/commands/cargo-fetch.md index bb5beda1e78..fa5158d8103 100644 --- a/src/doc/src/commands/cargo-fetch.md +++ b/src/doc/src/commands/cargo-fetch.md @@ -1,3 +1,155 @@ -# cargo fetch -{{#include command-common.html}} -{{#include ../../man/generated/cargo-fetch.html}} +# cargo-fetch(1) + + +## NAME + +cargo-fetch - Fetch dependencies of a package from the network + +## SYNOPSIS + +`cargo fetch` [_options_] + +## DESCRIPTION + +If a `Cargo.lock` file is available, this command will ensure that all of the +git dependencies and/or registry dependencies are downloaded and locally +available. Subsequent Cargo commands never touch the network after a `cargo +fetch` unless the lock file changes. + +If the lock file is not available, then this command will generate the lock +file before fetching the dependencies. + +If `--target` is not specified, then all target dependencies are fetched. + +See also the [cargo-prefetch](https://crates.io/crates/cargo-prefetch) +plugin which adds a command to download popular crates. This may be useful if +you plan to use Cargo without a network with the `--offline` flag. + +## OPTIONS + +### Fetch options + +
+
--target triple
+
Fetch for the given architecture. The default is the host +architecture. The general format of the triple is +<arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-update(1)](cargo-update.md), [cargo-generate-lockfile(1)](cargo-generate-lockfile.md) diff --git a/src/doc/src/commands/cargo-fix.md b/src/doc/src/commands/cargo-fix.md index 66503337a23..b811ab9eaa0 100644 --- a/src/doc/src/commands/cargo-fix.md +++ b/src/doc/src/commands/cargo-fix.md @@ -1,3 +1,436 @@ -# cargo fix -{{#include command-common.html}} -{{#include ../../man/generated/cargo-fix.html}} +# cargo-fix(1) + + +## NAME + +cargo-fix - Automatically fix lint warnings reported by rustc + +## SYNOPSIS + +`cargo fix` [_options_] + +## DESCRIPTION + +This Cargo subcommand will automatically take rustc's suggestions from +diagnostics like warnings and apply them to your source code. This is intended +to help automate tasks that rustc itself already knows how to tell you to fix! +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)](cargo-check.md). Any warnings +applicable to your crate will be automatically fixed (if possible) and all +remaining warnings will be displayed when the check process is finished. For +example if you'd like to prepare for the 2018 edition, you can do so by +executing: + + cargo fix --edition + +which behaves the same as `cargo check --all-targets`. + +`cargo fix` is only capable of fixing code that is normally compiled with +`cargo check`. If code is conditionally enabled with optional features, you +will need to enable those features for that code to be analyzed: + + cargo fix --edition --features foo + +Similarly, other `cfg` expressions like platform-specific code will need to +pass `--target` to fix code for the given target. + + cargo fix --edition --target x86_64-pc-windows-gnu + +If you encounter any problems with `cargo fix` or otherwise have any questions +or feature requests please don't hesitate to file an issue at + + +## 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 selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +
+ +
-p spec...
+
--package spec...
+
Fix only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Fix all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### 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 targets in test mode that have the test = true manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the test flag in the +manifest settings for the target.
+ + +
--bench name...
+
Fix the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Fix all targets in benchmark mode that have the bench = true +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the bench flag in the +manifest settings for the target.
+ + +
--all-targets
+
Fix all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Fix optimized artifacts with the release profile. 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + +
+ +### Manifest Options + +
+
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `test` | `bench` + +Dependencies use the `dev`/`release` profiles. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. Convert a 2015 edition to 2018: + + cargo fix --edition + +3. Apply suggested idioms for the current edition: + + cargo fix --edition-idioms + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-check(1)](cargo-check.md) diff --git a/src/doc/src/commands/cargo-generate-lockfile.md b/src/doc/src/commands/cargo-generate-lockfile.md index 57b70691138..79b1decc04e 100644 --- a/src/doc/src/commands/cargo-generate-lockfile.md +++ b/src/doc/src/commands/cargo-generate-lockfile.md @@ -1,3 +1,130 @@ -# cargo generate-lockfile -{{#include command-common.html}} -{{#include ../../man/generated/cargo-generate-lockfile.html}} +# cargo-generate-lockfile(1) + +## NAME + +cargo-generate-lockfile - Generate the lockfile for a package + +## SYNOPSIS + +`cargo generate-lockfile` [_options_] + +## DESCRIPTION + +This command will create the `Cargo.lock` lockfile for the current package or +workspace. If the lockfile already exists, it will be rebuilt if there are any +manifest changes or dependency updates. + +See also [cargo-update(1)](cargo-update.md) 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 for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-update(1)](cargo-update.md) diff --git a/src/doc/src/commands/cargo-help.md b/src/doc/src/commands/cargo-help.md index 7e1ba07307e..a5acfd284aa 100644 --- a/src/doc/src/commands/cargo-help.md +++ b/src/doc/src/commands/cargo-help.md @@ -1,3 +1,26 @@ -# cargo help -{{#include command-common.html}} -{{#include ../../man/generated/cargo-help.html}} +# cargo-help(1) + +## NAME + +cargo-help - Get help for a Cargo command + +## SYNOPSIS + +`cargo help` [_subcommand_] + +## DESCRIPTION + +Prints a help message for the given command. + +## EXAMPLES + +1. Get help for a command: + + cargo help build + +2. Help is also available with the `--help` flag: + + cargo build --help + +## SEE ALSO +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-init.md b/src/doc/src/commands/cargo-init.md index 044a8b12dca..b0389287c8f 100644 --- a/src/doc/src/commands/cargo-init.md +++ b/src/doc/src/commands/cargo-init.md @@ -1,3 +1,169 @@ -# cargo init -{{#include command-common.html}} -{{#include ../../man/generated/cargo-init.html}} +# cargo-init(1) + +## NAME + +cargo-init - Create a new Cargo package in an existing directory + +## SYNOPSIS + +`cargo init` [_options_] [_path_] + +## DESCRIPTION + +This command will create a new Cargo manifest in the current directory. Give a +path as an argument to create in the given directory. + +If there are typically-named Rust source files already in the directory, those +will be used. If not, then a sample `src/main.rs` file will be created, or +`src/lib.rs` if `--lib` is passed. + +If the directory is not already in a VCS repository, then a new repository +is created (see `--vcs` below). + +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](../reference/config.html) for more information about +configuration files. + + +See [cargo-new(1)](cargo-new.md) 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
+
This sets the publish field in Cargo.toml to the given registry name +which will restrict publishing only to that registry.

+

Registry names are defined in Cargo config files. +If not specified, the default registry defined by the registry.default +config key is used. If the default registry is not set and --registry is not +used, the publish field will not be set which means that publishing will not +be restricted.

+ + +
+ + +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-new(1)](cargo-new.md) diff --git a/src/doc/src/commands/cargo-install.md b/src/doc/src/commands/cargo-install.md index 5fa11a60d57..bb11620fb8a 100644 --- a/src/doc/src/commands/cargo-install.md +++ b/src/doc/src/commands/cargo-install.md @@ -1,3 +1,354 @@ -# cargo install -{{#include command-common.html}} -{{#include ../../man/generated/cargo-install.html}} +# cargo-install(1) + + +## 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 executable `[[bin]]` or `[[example]]` targets can be +installed, and all executables are installed into the installation root's +`bin` folder. + +The installation root is determined, in order of precedence: + +- `--root` option +- `CARGO_INSTALL_ROOT` environment variable +- `install.root` Cargo [config value](../reference/config.html) +- `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`, `--path`, and `--registry` flags can +change this source. If the source contains more than one package (such as +crates.io or a git repository with multiple crates) the _crate_ argument is +required to indicate which crate should be installed. + +Crates from crates.io can optionally specify the version they wish to install +via the `--version` flags, and similarly packages from git repositories can +optionally specify the branch, tag, or revision that should be installed. If a +crate has multiple binaries, the `--bin` argument can selectively install only +one of them, and if you'd rather install examples the `--example` argument can +be used as well. + +If the package is already installed, Cargo will reinstall it if the installed +version does not appear to be up-to-date. If any of the following values +change, then Cargo will reinstall the package: + +- The package version and source. +- The set of binary names installed. +- The chosen features. +- The release mode (`--debug`). +- The target (`--target`). + +Installing with `--path` will always build and install, unless there are +conflicting binaries from another package. The `--force` flag may be used to +force Cargo to always reinstall the package. + +If the source is crates.io or `--git` then by default the crate will be built +in a temporary target directory. To avoid this, the target directory can be +specified by setting the `CARGO_TARGET_DIR` environment variable to a relative +path. In particular, this can be useful for caching build artifacts on +continuous integration systems. + +By default, the `Cargo.lock` file that is included with the package will be +ignored. This means that Cargo will recompute which versions of dependencies +to use, possibly using newer versions that have been released since the +package was published. The `--locked` flag can be used to force Cargo to use +the packaged `Cargo.lock` file if it is available. This may be useful for +ensuring reproducible builds, to use the exact same set of dependencies that +were available when the package was published. It may also be useful if a +newer version of a dependency is published that no longer builds on your +system, or has other problems. The downside to using `--locked` is that you +will not receive any fixes or updates to any dependency. Note that Cargo did +not start publishing `Cargo.lock` files until version 1.37, which means +packages published with prior versions will not have a `Cargo.lock` file +available. + +## OPTIONS + +### Install Options + +
+ +
--vers version
+
--version version
+
Specify a version to install. This may be a version +requirement, like ~1.2, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as ^ or ~), then it must be in the form +MAJOR.MINOR.PATCH, and will install exactly that version; it is not +treated as a caret requirement like Cargo dependencies are.
+ + +
--git url
+
Git URL to install the specified crate from.
+ + +
--branch branch
+
Branch to use when installing from git.
+ + +
--tag tag
+
Tag to use when installing from git.
+ + +
--rev sha
+
Specific commit to use when installing from git.
+ + +
--path path
+
Filesystem path to local crate to install.
+ + +
--list
+
List all installed packages and their versions.
+ + +
-f
+
--force
+
Force overwriting existing crates or binaries. This can be used if a package +has installed a binary with the same name as another package. This is also +useful if something has changed on the system that you want to rebuild with, +such as a newer version of rustc.
+ + +
--no-track
+
By default, Cargo keeps track of the installed packages with a metadata file +stored in the installation root directory. This flag tells Cargo not to use or +create that file. With this flag, Cargo will refuse to overwrite any existing +files unless the --force flag is used. This also disables Cargo's ability to +protect against multiple concurrent invocations of Cargo installing at the +same time.
+ + +
--bin name...
+
Install only the specified binary.
+ + +
--bins
+
Install all binaries.
+ + +
--example name...
+
Install only the specified example.
+ + +
--examples
+
Install all examples.
+ + +
--root dir
+
Directory to install packages into.
+ + +
--registry registry
+
Name of the registry to use. Registry names are defined in Cargo config +files. If not specified, the default registry is used, +which is defined by the registry.default config key which defaults to +crates-io.
+ + + +
--index index
+
The URL of the registry index to use.
+ + + +
+ +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--target-dir directory
+
Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.
+ + + +
--debug
+
Build with the dev profile instead the release profile.
+ + +
+ +### Manifest Options + +
+
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### 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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Install or upgrade a package from crates.io: + + cargo install ripgrep + +2. Install or reinstall the package in the current directory: + + cargo install --path . + +3. View the list of installed packages: + + cargo install --list + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-uninstall(1)](cargo-uninstall.md), [cargo-search(1)](cargo-search.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-locate-project.md b/src/doc/src/commands/cargo-locate-project.md index 0e42adfe404..dff40101277 100644 --- a/src/doc/src/commands/cargo-locate-project.md +++ b/src/doc/src/commands/cargo-locate-project.md @@ -1,3 +1,104 @@ -# cargo locate-project -{{#include command-common.html}} -{{#include ../../man/generated/cargo-locate-project.html}} +# cargo-locate-project(1) + +## NAME + +cargo-locate-project - Print a JSON representation of a Cargo.toml file's location + +## SYNOPSIS + +`cargo locate-project` [_options_] + +## DESCRIPTION + +This command will print a JSON object to stdout with the full path to the +`Cargo.toml` manifest. + +See also [cargo-metadata(1)](cargo-metadata.md) 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 for the +Cargo.toml file in the current directory or any parent directory.
+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-metadata(1)](cargo-metadata.md) diff --git a/src/doc/src/commands/cargo-login.md b/src/doc/src/commands/cargo-login.md index 5feddeead3e..601e49f246b 100644 --- a/src/doc/src/commands/cargo-login.md +++ b/src/doc/src/commands/cargo-login.md @@ -1,3 +1,111 @@ -# cargo login -{{#include command-common.html}} -{{#include ../../man/generated/cargo-login.html}} +# cargo-login(1) + +## NAME + +cargo-login - Save an API token from the registry locally + +## SYNOPSIS + +`cargo login` [_options_] [_token_] + +## DESCRIPTION + +This command will save the API token to disk so that commands that require +authentication, such as [cargo-publish(1)](cargo-publish.md), will be automatically +authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` +defaults to `.cargo` in your home directory. + +If the _token_ argument is not specified, it will be read from stdin. + +The API token for crates.io may be retrieved from . + +Take care to keep the token secret, it should not be shared with anyone else. + +## OPTIONS + +### Login Options + +
+
--registry registry
+
Name of the registry to use. Registry names are defined in Cargo config +files. If not specified, the default registry is used, +which is defined by the registry.default config key which defaults to +crates-io.
+ + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-metadata.md b/src/doc/src/commands/cargo-metadata.md index 273221395e7..0e0edcdc405 100644 --- a/src/doc/src/commands/cargo-metadata.md +++ b/src/doc/src/commands/cargo-metadata.md @@ -1,3 +1,448 @@ -# cargo metadata -{{#include command-common.html}} -{{#include ../../man/generated/cargo-metadata.html}} +# cargo-metadata(1) +:source-highlighter: highlightjs + +## NAME + +cargo-metadata - Machine-readable metadata about the current package + +## SYNOPSIS + +`cargo metadata` [_options_] + +## DESCRIPTION + +Output JSON to stdout containing information about the workspace members and +resolved dependencies of the current package. + +It is recommended to include the `--format-version` flag to future-proof +your code to ensure the output is in the format you are expecting. + +See the [cargo_metadata crate](https://crates.io/crates/cargo_metadata) +for a Rust API for reading the metadata. + +## OUTPUT FORMAT + +The output has the following format: + +```javascript +{ + /* Array of all packages in the workspace. + It also includes all feature-enabled dependencies unless --no-deps is used. + */ + "packages": [ + { + /* The name of the package. */ + "name": "my-package", + /* The version of the package. */ + "version": "0.1.0", + /* The Package ID, a unique identifier for referring to the package. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The license value from the manifest, or null. */ + "license": "MIT/Apache-2.0", + /* The license-file value from the manifest, or null. */ + "license_file": "LICENSE", + /* The description value from the manifest, or null. */ + "description": "Package description.", + /* The source ID of the package. This represents where + a package is retrieved from. + This is null for path dependencies and workspace members. + For other dependencies, it is a string with the format: + - "registry+URL" for registry-based dependencies. + Example: "registry+https://github.com/rust-lang/crates.io-index" + - "git+URL" for git-based dependencies. + Example: "git+https://github.com/rust-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" + */ + "source": null, + /* Array of dependencies declared in the package's manifest. */ + "dependencies": [ + { + /* The name of the dependency. */ + "name": "bitflags", + /* The source ID of the dependency. May be null, see + description for the package source. + */ + "source": "registry+https://github.com/rust-lang/crates.io-index", + /* The version requirement for the dependency. + Dependencies without a version requirement have a value of "*". + */ + "req": "^1.0", + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* If the dependency is renamed, this is the new name for + the dependency as a string. null if it is not renamed. + */ + "rename": null, + /* Boolean of whether or not this is an optional dependency. */ + "optional": false, + /* Boolean of whether or not default features are enabled. */ + "uses_default_features": true, + /* Array of features enabled. */ + "features": [], + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)", + /* A string of the URL of the registry this dependency is from. + If not specified or null, the dependency is from the default + registry (crates.io). + */ + "registry": null + } + ], + /* Array of Cargo targets. */ + "targets": [ + { + /* Array of target kinds. + - lib targets list the `crate-type` values from the + manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - binary is ["bin"] + - example is ["example"] + - integration test is ["test"] + - benchmark is ["bench"] + - build script is ["custom-build"] + */ + "kind": [ + "bin" + ], + /* Array of crate types. + - lib and example libraries list the `crate-type` values + from the manifest such as "lib", "rlib", "dylib", + "proc-macro", etc. (default ["lib"]) + - all other target kinds are ["bin"] + */ + "crate_types": [ + "bin" + ], + /* The name of the target. */ + "name": "my-package", + /* Absolute path to the root source file of the target. */ + "src_path": "/path/to/my-package/src/main.rs", + /* The Rust edition of the target. + Defaults to the package edition. + */ + "edition": "2018", + /* Array of required features. + This property is not included if no required features are set. + */ + "required-features": ["feat1"], + /* Whether or not this target has doc tests enabled, and + the target is compatible with doc testing. + */ + "doctest": false, + /* Whether or not this target should be built and run with `--test` + */ + "test": true + } + ], + /* Set of features defined for the package. + Each feature maps to an array of features or dependencies it + enables. + */ + "features": { + "default": [ + "feat1" + ], + "feat1": [], + "feat2": [] + }, + /* Absolute path to this package's manifest. */ + "manifest_path": "/path/to/my-package/Cargo.toml", + /* Package metadata. + This is null if no metadata is specified. + */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + }, + /* List of registries to which this package may be published. + Publishing is unrestricted if null, and forbidden if an empty array. */ + "publish": [ + "crates-io" + ], + /* Array of authors from the manifest. + Empty array if no authors specified. + */ + "authors": [ + "Jane Doe " + ], + /* Array of categories from the manifest. */ + "categories": [ + "command-line-utilities" + ], + /* Array of keywords from the manifest. */ + "keywords": [ + "cli" + ], + /* The readme value from the manifest or null if not specified. */ + "readme": "README.md", + /* The repository value from the manifest or null if not specified. */ + "repository": "https://github.com/rust-lang/cargo", + /* The default edition of the package. + Note that individual targets may have different editions. + */ + "edition": "2018", + /* Optional string that is the name of a native library the package + is linking to. + */ + "links": null, + } + ], + /* Array of members of the workspace. + Each entry is the Package ID for the package. + */ + "workspace_members": [ + "my-package 0.1.0 (path+file:///path/to/my-package)", + ], + // The resolved dependency graph for the entire workspace. The enabled + // features are based on the enabled features for the "current" package. + // Inactivated optional dependencies are not listed. + // + // This is null if --no-deps is specified. + // + // By default, this includes all dependencies for all target platforms. + // The `--filter-platform` flag may be used to narrow to a specific + // target triple. + "resolve": { + /* Array of nodes within the dependency graph. + Each node is a package. + */ + "nodes": [ + { + /* The Package ID of this node. */ + "id": "my-package 0.1.0 (path+file:///path/to/my-package)", + /* The dependencies of this package, an array of Package IDs. */ + "dependencies": [ + "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" + ], + /* The dependencies of this package. This is an alternative to + "dependencies" which contains additional information. In + particular, this handles renamed dependencies. + */ + "deps": [ + { + /* The name of the dependency's library target. + If this is a renamed dependency, this is the new + name. + */ + "name": "bitflags", + /* The Package ID of the dependency. */ + "pkg": "bitflags 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", + /* Array of dependency kinds. Added in Cargo 1.40. */ + "dep_kinds": [ + { + /* The dependency kind. + "dev", "build", or null for a normal dependency. + */ + "kind": null, + /* The target platform for the dependency. + null if not a target dependency. + */ + "target": "cfg(windows)" + } + ] + } + ], + /* Array of features enabled on this package. */ + "features": [ + "default" + ] + } + ], + /* The root package of the workspace. + This is null if this is a virtual workspace. Otherwise it is + the Package ID of the root package. + */ + "root": "my-package 0.1.0 (path+file:///path/to/my-package)" + }, + /* The absolute path to the build directory where Cargo places its output. */ + "target_directory": "/path/to/my-package/target", + /* The version of the schema for this metadata structure. + This will be changed if incompatible changes are ever made. + */ + "version": 1, + /* The absolute path to the root of the workspace. */ + "workspace_root": "/path/to/my-package" + /* Workspace metadata. + This is null if no metadata is specified. */ + "metadata": { + "docs": { + "rs": { + "all-features": true + } + } + } +} +```` + +## OPTIONS + +### Output Options + +
+ +
--no-deps
+
Output information only about the workspace members and don't fetch +dependencies.
+ + +
--format-version version
+
Specify the version of the output format to use. Currently 1 is the only +possible value.
+ + +
--filter-platform triple
+
This filters the resolve output to only include dependencies for the +given target triple. Without this flag, the resolve includes all targets.

+

Note that the dependencies listed in the "packages" array still includes all +dependencies. Each package definition is intended to be an unaltered +reproduction of the information within Cargo.toml.

+ + +
+ +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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 for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-new.md b/src/doc/src/commands/cargo-new.md index 3f1a490244d..27d4ca316e8 100644 --- a/src/doc/src/commands/cargo-new.md +++ b/src/doc/src/commands/cargo-new.md @@ -1,3 +1,164 @@ -# cargo new -{{#include command-common.html}} -{{#include ../../man/generated/cargo-new.html}} +# cargo-new(1) + +## NAME + +cargo-new - Create a new Cargo package + +## SYNOPSIS + +`cargo new` [_options_] _path_ + +## DESCRIPTION + +This command will create a new Cargo package in the given directory. This +includes a simple template with a `Cargo.toml` manifest, sample source file, +and a VCS ignore file. If the directory is not already in a VCS repository, +then a new repository is created (see `--vcs` below). + +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](../reference/config.html) for more information about +configuration files. + + +See [cargo-init(1)](cargo-init.md) 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
+
This sets the publish field in Cargo.toml to the given registry name +which will restrict publishing only to that registry.

+

Registry names are defined in Cargo config files. +If not specified, the default registry defined by the registry.default +config key is used. If the default registry is not set and --registry is not +used, the publish field will not be set which means that publishing will not +be restricted.

+ + +
+ + +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-init(1)](cargo-init.md) diff --git a/src/doc/src/commands/cargo-owner.md b/src/doc/src/commands/cargo-owner.md index c1dbc9eb6c7..a5aaee9ef69 100644 --- a/src/doc/src/commands/cargo-owner.md +++ b/src/doc/src/commands/cargo-owner.md @@ -1,3 +1,157 @@ -# cargo owner -{{#include command-common.html}} -{{#include ../../man/generated/cargo-owner.html}} +# cargo-owner(1) + +## NAME + +cargo-owner - Manage the owners of a crate on the registry + +## SYNOPSIS + +`cargo owner` [_options_] `--add` _login_ [_crate_]\ +`cargo owner` [_options_] `--remove` _login_ [_crate_]\ +`cargo owner` [_options_] `--list` [_crate_] + +## DESCRIPTION + +This command will modify the owners for a crate on the registry. Owners of a +crate can upload new versions and yank old versions. Non-team owners can also +modify the set of owners, so take care! + +This command requires you to be authenticated with either the `--token` option +or using [cargo-login(1)](cargo-login.md). + +If the crate name is not specified, it will use the package name from the +current directory. + +See [the reference](../reference/publishing.html#cargo-owner) for more +information about owners and publishing. + +## OPTIONS + +### Owner Options + +
+ +
-a
+
--add login...
+
Invite the given user or team as an owner.
+ + +
-r
+
--remove login...
+
Remove the given user or team as an owner.
+ + +
-l
+
--list
+
List owners of a crate.
+ + +
--token token
+
API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by cargo-login(1)).

+

Cargo config environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the CARGO_REGISTRY_TOKEN environment +variable. Tokens for other registries may be specified with environment +variables of the form CARGO_REGISTRIES_NAME_TOKEN where NAME is the name +of the registry in all capital letters.

+ + + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in Cargo config +files. If not specified, the default registry is used, +which is defined by the registry.default config key which defaults to +crates-io.
+ + + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. Invite an owner to a package: + + cargo owner --add username foo + +3. Remove an owner from a package: + + cargo owner --remove username foo + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-login(1)](cargo-login.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-package.md b/src/doc/src/commands/cargo-package.md index 8bfedcfa40d..0cab5b3feac 100644 --- a/src/doc/src/commands/cargo-package.md +++ b/src/doc/src/commands/cargo-package.md @@ -1,3 +1,251 @@ -# cargo package -{{#include command-common.html}} -{{#include ../../man/generated/cargo-package.html}} +# cargo-package(1) + + +## NAME + +cargo-package - Assemble the local package into a distributable tarball + +## SYNOPSIS + +`cargo package` [_options_] + +## DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory. The resulting file will +be stored in the `target/package` directory. This performs the following +steps: + +1. Load and check the current workspace, performing some basic checks. + - Path dependencies are not allowed unless they have a version key. Cargo + will ignore the path key for dependencies in published packages. + `dev-dependencies` do not have this restriction. +2. Create the compressed `.crate` file. + - The original `Cargo.toml` file is rewritten and normalized. + - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the + manifest. + - `Cargo.lock` is automatically included if the package contains an + executable binary or example target. [cargo-install(1)](cargo-install.md) will use the + packaged lock file if the `--locked` flag is used. + - A `.cargo_vcs_info.json` file is included that contains information + about the current VCS checkout hash if available (not included with + `--allow-dirty`). +3. Extract the `.crate` file and build it to verify it can build. + - This will rebuild your package from scratch to ensure that it can be + built from a pristine state. The `--no-verify` flag can be used to skip + this step. +4. Check that build scripts did not modify any source files. + +The list of files included can be controlled with the `include` and `exclude` +fields in the manifest. + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +## 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--target-dir directory
+
Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.
+ + + +
+ +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Manifest Options + +
+ +
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### 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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-pkgid.md b/src/doc/src/commands/cargo-pkgid.md index 7481ad1c7af..866888acaac 100644 --- a/src/doc/src/commands/cargo-pkgid.md +++ b/src/doc/src/commands/cargo-pkgid.md @@ -1,3 +1,167 @@ -# cargo pkgid -{{#include command-common.html}} -{{#include ../../man/generated/cargo-pkgid.html}} +# cargo-pkgid(1) + +## NAME + +cargo-pkgid - Print a fully qualified package specification + +## SYNOPSIS + +`cargo pkgid` [_options_] [_spec_] + +## DESCRIPTION + +Given a _spec_ argument, print out the fully qualified package ID specifier +for a package or dependency in the current workspace. This command will +generate an error if _spec_ is ambiguous as to which package it refers to in +the dependency graph. If no _spec_ is given, then the specifier for the local +package is printed. + +This command requires that a lockfile is available and dependencies have been +fetched. + +A package specifier consists of a name, version, and source URL. You are +allowed to use partial specifiers to succinctly match a specific package as +long as it matches only one package. The format of a _spec_ can be one of the +following: + +SPEC Structure | Example SPEC +---------------------------|-------------- +_name_ | `bitflags` +_name_`:`_version_ | `bitflags:1.0.4` +_url_ | `https://github.com/rust-lang/cargo` +_url_`#`_version_ | `https://github.com/rust-lang/cargo#0.33.0` +_url_`#`_name_ | `https://github.com/rust-lang/crates.io-index#bitflags` +_url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io:0.21.0` + +## OPTIONS + +### Package Selection + +
+ +
-p spec
+
--package spec
+
Get the package ID for the given package instead of the current package.
+ + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. Retrieve package specification for version 1.0.0 of `foo`: + + cargo pkgid foo:1.0.0 + +3. Retrieve package specification for `foo` from crates.io: + + cargo pkgid https://github.com/rust-lang/crates.io-index#foo + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-generate-lockfile(1)](cargo-generate-lockfile.md), [cargo-metadata(1)](cargo-metadata.md) diff --git a/src/doc/src/commands/cargo-publish.md b/src/doc/src/commands/cargo-publish.md index db45e789908..f881c32977e 100644 --- a/src/doc/src/commands/cargo-publish.md +++ b/src/doc/src/commands/cargo-publish.md @@ -1,3 +1,257 @@ -# cargo publish -{{#include command-common.html}} -{{#include ../../man/generated/cargo-publish.html}} +# cargo-publish(1) + + +## NAME + +cargo-publish - Upload a package to the registry + +## SYNOPSIS + +`cargo publish` [_options_] + +## DESCRIPTION + +This command will create a distributable, compressed `.crate` file with the +source code of the package in the current directory and upload it to a +registry. The default registry is . This performs the +following steps: + +1. Performs a few checks, including: + - Checks the `package.publish` key in the manifest for restrictions on + which registries you are allowed to publish to. +2. Create a `.crate` file by following the steps in [cargo-package(1)](cargo-package.md). +3. Upload the crate to the registry. Note that the server will perform + additional checks on the crate. + +This command requires you to be authenticated with either the `--token` option +or using [cargo-login(1)](cargo-login.md). + +See [the reference](../reference/publishing.html) for more details about +packaging and publishing. + +## OPTIONS + +### Publish Options + +
+ +
--dry-run
+
Perform all checks without uploading.
+ + +
--token token
+
API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by cargo-login(1)).

+

Cargo config environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the CARGO_REGISTRY_TOKEN environment +variable. Tokens for other registries may be specified with environment +variables of the form CARGO_REGISTRIES_NAME_TOKEN where NAME is the name +of the registry in all capital letters.

+ + + +
--no-verify
+
Don't verify the contents by building them.
+ + +
--allow-dirty
+
Allow working directories with uncommitted VCS changes to be packaged.
+ + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in Cargo config +files. If not specified, the default registry is used, +which is defined by the registry.default config key which defaults to +crates-io.
+ + + +
+ +### Compilation Options + +
+ +
--target triple
+
Publish for the given architecture. The default is the host +architecture. The general format of the triple is +<arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--target-dir directory
+
Directory for all generated artifacts and intermediate files. May also be +specified with the CARGO_TARGET_DIR environment variable, or the +build.target-dir config value. Defaults +to target in the root of the workspace.
+ + + +
+ +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the current directory's package.
+ + +
+ + +### Manifest Options + +
+ +
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### 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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-package(1)](cargo-package.md), [cargo-login(1)](cargo-login.md) diff --git a/src/doc/src/commands/cargo-run.md b/src/doc/src/commands/cargo-run.md index 16d92815f09..40c56b7ee84 100644 --- a/src/doc/src/commands/cargo-run.md +++ b/src/doc/src/commands/cargo-run.md @@ -1,3 +1,294 @@ -# cargo run -{{#include command-common.html}} -{{#include ../../man/generated/cargo-run.html}} +# cargo-run(1) + + +## NAME + +cargo-run - Run the current package + +## SYNOPSIS + +`cargo run` [_options_] [`--` _args_] + +## DESCRIPTION + +Run a binary or example of the local package. + +All the arguments following the two dashes (`--`) are passed to the binary to +run. If you're passing arguments to both Cargo and the binary, the ones after +`--` go to the binary, the ones before go to Cargo. + +## OPTIONS + +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +
+ +
-p spec
+
--package spec
+
The package to run. See cargo-pkgid(1) for the SPEC +format.
+ + +
+ + +### Target Selection + +When no target selection options are given, `cargo run` will run the binary +target. If there are multiple binary targets, you must pass a target flag to +choose one. Or, the `default-run` field may be specified in the `[package]` +section of `Cargo.toml` to choose the name of the binary to run by default. + +
+ +
--bin name
+
Run the specified binary.
+ + +
--example name
+
Run the specified example.
+ + +
+ +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Run optimized artifacts with the release profile. 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + + +
+ +### Manifest Options + +
+ +
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `test` | `bench` + +Dependencies use the `dev`/`release` profiles. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 (assuming only one binary): + + cargo run + +2. Run an example with extra arguments: + + cargo run --example exname -- --exoption exarg1 exarg2 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md) diff --git a/src/doc/src/commands/cargo-rustc.md b/src/doc/src/commands/cargo-rustc.md index ad6b3d98774..c0d4bf24fc9 100644 --- a/src/doc/src/commands/cargo-rustc.md +++ b/src/doc/src/commands/cargo-rustc.md @@ -1,3 +1,356 @@ -# cargo rustc -{{#include command-common.html}} -{{#include ../../man/generated/cargo-rustc.html}} +# cargo-rustc(1) + + +## NAME + +cargo-rustc - Compile the current package, and pass extra options to the compiler + +## SYNOPSIS + +`cargo rustc` [_options_] [`--` _args_] + +## DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be compiled along with all of its dependencies. The specified +_args_ will all be passed to the final compiler invocation, not any of the +dependencies. Note that the compiler will still unconditionally receive +arguments such as `-L`, `--extern`, and `--crate-type`, and the specified +_args_ will simply be added to the compiler invocation. + +See 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](../reference/environment-variables.html) or the +`build.rustflags` [config value](../reference/config.html). + +## OPTIONS + +### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +
+ +
-p spec
+
--package spec
+
The package to build. See cargo-pkgid(1) for the SPEC +format.
+ + +
+ + +### Target Selection + +When no target selection options are given, `cargo rustc` will build all +binary and library targets of the selected package. + +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 targets in test mode that have the test = true manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the test flag in the +manifest settings for the target.
+ + +
--bench name...
+
Build the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Build all targets in benchmark mode that have the bench = true +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the bench flag in the +manifest settings for the target.
+ + +
--all-targets
+
Build all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Build optimized artifacts with the release profile. 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + + +
+ +### Manifest Options + +
+ +
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `test` | `bench` + +Dependencies use the `dev`/`release` profiles. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. 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 +[cargo(1)](cargo.md), [cargo-build(1)](cargo-build.md), [rustc(1)](https://doc.rust-lang.org/rustc/index.html) diff --git a/src/doc/src/commands/cargo-rustdoc.md b/src/doc/src/commands/cargo-rustdoc.md index a8ebf1950ea..8659e08eced 100644 --- a/src/doc/src/commands/cargo-rustdoc.md +++ b/src/doc/src/commands/cargo-rustdoc.md @@ -1,3 +1,360 @@ -# cargo rustdoc -{{#include command-common.html}} -{{#include ../../man/generated/cargo-rustdoc.html}} +# cargo-rustdoc(1) + + +## NAME + +cargo-rustdoc - Build a package's documentation, using specified custom flags + +## SYNOPSIS + +`cargo rustdoc` [_options_] [`--` _args_] + +## DESCRIPTION + +The specified target for the current package (or package specified by `-p` if +provided) will be documented with the specified _args_ being passed to the +final rustdoc invocation. Dependencies will not be documented as part of this +command. Note that rustdoc will still unconditionally receive arguments such +as `-L`, `--extern`, and `--crate-type`, and the specified _args_ will simply +be added to the rustdoc invocation. + +See 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](../reference/environment-variables.html) +or the `build.rustdocflags` [config value](../reference/config.html). + +## OPTIONS + +### Documentation Options + +
+ +
--open
+
Open the docs in a browser after building them. This will use your default +browser unless you define another one in the BROWSER environment variable.
+ + +
+ +### 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 targets in test mode that have the test = true manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the test flag in the +manifest settings for the target.
+ + +
--bench name...
+
Document the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Document all targets in benchmark mode that have the bench = true +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the bench flag in the +manifest settings for the target.
+ + +
--all-targets
+
Document all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Document optimized artifacts with the release profile. 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + +
+ +### Manifest Options + +
+
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `test` | `bench` + +Dependencies use the `dev`/`release` profiles. + + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-doc(1)](cargo-doc.md), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/doc/src/commands/cargo-search.md b/src/doc/src/commands/cargo-search.md index b872d9628fb..ed5de00e34d 100644 --- a/src/doc/src/commands/cargo-search.md +++ b/src/doc/src/commands/cargo-search.md @@ -1,3 +1,115 @@ -# cargo search -{{#include command-common.html}} -{{#include ../../man/generated/cargo-search.html}} +# cargo-search(1) + +## NAME + +cargo-search - Search packages in crates.io + +## SYNOPSIS + +`cargo search` [_options_] [_query_...] + +## DESCRIPTION + +This performs a textual search for crates on . The matching +crates will be displayed along with their description in TOML format suitable +for copying into a `Cargo.toml` manifest. + +## OPTIONS + +### Search Options + +
+ +
--limit limit
+
Limit the number of results (default: 10, max: 100).
+ + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in Cargo config +files. If not specified, the default registry is used, +which is defined by the registry.default config key which defaults to +crates-io.
+ + + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-install(1)](cargo-install.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo-test.md b/src/doc/src/commands/cargo-test.md index 52fc969128d..31f18e559c2 100644 --- a/src/doc/src/commands/cargo-test.md +++ b/src/doc/src/commands/cargo-test.md @@ -1,3 +1,468 @@ -# cargo test -{{#include command-common.html}} -{{#include ../../man/generated/cargo-test.html}} +# cargo-test(1) + + + +## NAME + +cargo-test - Execute unit and integration tests of a package + +## SYNOPSIS + +`cargo test` [_options_] [_testname_] [`--` _test-options_] + +## DESCRIPTION + +Compile and execute unit and integration tests. + +The test filtering argument `TESTNAME` and all the arguments following the two +dashes (`--`) are passed to the test binaries and thus to _libtest_ (rustc's +built in unit-test and micro-benchmarking framework). If you're passing +arguments to both Cargo and the binary, the ones after `--` go to the binary, +the ones before go to Cargo. For details about libtest's arguments see the +output of `cargo test -- --help`. + +As an example, this will filter for tests with `foo` in their name and run them +on 3 threads in parallel: + + cargo test foo -- --test-threads 3 + +Tests are built with the `--test` option to `rustc` which creates an +executable with a `main` function that automatically runs all functions +annotated with the `#[test]` attribute in multiple threads. `#[bench]` +annotated functions will also be run with one iteration to verify that they +are functional. + +The libtest harness may be disabled by setting `harness = false` in the target +manifest settings, in which case your code will need to provide its own `main` +function to handle running tests. + +Documentation tests are also run by default, which is handled by `rustdoc`. It +extracts code samples from documentation comments and executes them. See the +[rustdoc book](https://doc.rust-lang.org/rustdoc/) for more information on +writing doc tests. + +## OPTIONS + +### Test Options + +
+ +
--no-run
+
Compile, but don't run tests.
+ + +
--no-fail-fast
+
Run all tests regardless of failure. Without this flag, Cargo will exit +after the first executable fails. The Rust test harness will run all tests +within the executable to completion, this flag only applies to the executable +as a whole.
+ + +
+ + +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +
+ +
-p spec...
+
--package spec...
+
Test only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Test all members in the workspace.
+ + + +
--all
+
Deprecated alias for --workspace.
+ + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### Target Selection + +When no target selection options are given, `cargo test` will build the +following targets of the selected packages: + +- lib — used to link with binaries, examples, integration tests, and doc tests +- bins (only if integration tests are built and required features are + available) +- examples — to ensure they compile +- lib as a unit test +- bins as unit tests +- integration tests +- doc tests for the lib target + +The default behavior can be changed by setting the `test` flag for the target +in the manifest settings. Setting examples to `test = true` will build and run +the example as a test. Setting targets to `test = false` will stop them from +being tested by default. Target selection options that take a target by name +ignore the `test` flag and will always test the given target. + +Doc tests for libraries may be disabled by setting `doctest = false` for the +library in the manifest. + +Binary targets are automatically built if there is an integration test or +benchmark. This allows an integration test to execute the binary to exercise +and test its behavior. The `CARGO_bin_EXE_` +[environment variable](../reference/environment-variables.html#environment-variables-cargo-sets-for-crates) +is set when the integration test is built so that it can use the +[`env` macro](https://doc.rust-lang.org/std/macro.env.html) to locate the +executable. + +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 targets in test mode that have the test = true manifest +flag set. By default this includes the library and binaries built as +unittests, and integration tests. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +unittest, and once as a dependency for binaries, integration tests, etc.). +Targets may be enabled or disabled by setting the test flag in the +manifest settings for the target.
+ + +
--bench name...
+
Test the specified benchmark. This flag may be specified multiple times.
+ + +
--benches
+
Test all targets in benchmark mode that have the bench = true +manifest flag set. By default this includes the library and binaries built +as benchmarks, and bench targets. Be aware that this will also build any +required dependencies, so the lib target may be built twice (once as a +benchmark, and once as a dependency for binaries, benchmarks, etc.). +Targets may be enabled or disabled by setting the bench flag in the +manifest settings for the target.
+ + +
--all-targets
+
Test all targets. This is equivalent to specifying --lib --bins --tests --benches --examples.
+ + +
+ + +
+ +
--doc
+
Test only the library's documentation. This cannot be mixed with other +target options.
+ + +
+ +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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>. Run rustc --print target-list for a +list of supported targets.

+

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

+

Note that specifying this flag makes Cargo run in a different mode where the +target artifacts are placed in a separate directory. See the +build cache documentation for more details.

+ + + +
--release
+
Test optimized artifacts with the release profile. 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. Can be specified multiple times +and consists of comma-separated values. Valid values:

+
    +
  • human (default): Display in a human-readable text format.
    • +
  • short: Emit shorter, human-readable text messages.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted.
    • +
+ + + +
+ +### Manifest Options + +
+ +
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +### 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](../reference/profiles.html) 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, or any target in "test" or "bench" mode | `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](../reference/environment-variables.html) 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. Run only tests whose names match against a filter string: + + cargo test name_filter + +3. Run only a specific test within a specific integration test: + + cargo test --test int_test_name -- modname::test_name + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-bench(1)](cargo-bench.md) diff --git a/src/doc/src/commands/cargo-tree.md b/src/doc/src/commands/cargo-tree.md index 0b134a71569..96adb5ccd8b 100644 --- a/src/doc/src/commands/cargo-tree.md +++ b/src/doc/src/commands/cargo-tree.md @@ -1,3 +1,384 @@ -# cargo tree -{{#include command-common.html}} -{{#include ../../man/generated/cargo-tree.html}} +# cargo-tree(1) + + + +## NAME + +cargo-tree - Display a tree visualization of a dependency graph + +## SYNOPSIS + +`cargo tree` [_options_] + +## DESCRIPTION + +This command will display a tree of dependencies to the terminal. An example +of a simple project that depends on the "rand" package: + +``` +myproject v0.1.0 (/myproject) +└── rand v0.7.3 + ├── getrandom v0.1.14 + │ ├── cfg-if v0.1.10 + │ └── libc v0.2.68 + ├── libc v0.2.68 (*) + ├── rand_chacha v0.2.2 + │ ├── ppv-lite86 v0.2.6 + │ └── rand_core v0.5.1 + │ └── getrandom v0.1.14 (*) + └── rand_core v0.5.1 (*) +[build-dependencies] +└── cc v1.0.50 +``` + +Packages marked with `(*)` have been "de-duplicated". The dependencies for the +package have already been shown elswhere in the graph, and so are not +repeated. Use the `--no-dedupe` option to repeat the duplicates. + +The `-e` flag can be used to select the dependency kinds to display. The +"features" kind changes the output to display the features enabled by +each dependency. For example, `cargo tree -e features`: + +``` +myproject v0.1.0 (/myproject) +└── log feature "serde" + └── log v0.4.8 + ├── serde v1.0.106 + └── cfg-if feature "default" + └── cfg-if v0.1.10 +``` + +In this tree, `myproject` depends on `log` with the `serde` feature. `log` in +turn depends on `cfg-if` with "default" features. When using `-e features` it +can be helpful to use `-i` flag to show how the features flow into a package. +See the examples below for more detail. + +## OPTIONS + +### Tree Options + +
+ +
-i spec
+
--invert spec
+
Show the reverse dependencies for the given package. This flag will invert +the tree and display the packages that depend on the given package.

+

Note that in a workspace, by default it will only display the package's +reverse dependencies inside the tree of the workspace member in the current +directory. The --workspace flag can be used to extend it so that it will +show the package's reverse dependencies across the entire workspace. The -p +flag can be used to display the package's reverse dependencies only with the +subtree of the package given to -p.

+ + +
--no-dedupe
+
Do not de-duplicate repeated dependencies. Usually, when a package has already +displayed its dependencies, further occurrences will not re-display its +dependencies, and will include a (*) to indicate it has already been shown. +This flag will cause those duplicates to be repeated.
+ + +
-d
+
--duplicates
+
Show only dependencies which come in multiple versions (implies --invert). +When used with the -p flag, only shows duplicates within the subtree of the +given package.

+

It can be beneficial for build times and executable sizes to avoid building +that same package multiple times. This flag can help identify the offending +packages. You can then investigate if the package that depends on the +duplicate with the older version can be updated to the newer version so that +only one instance is built.

+ + +
-e kinds
+
--edges kinds
+
The dependency kinds to display. Takes a comma separated list of values:

+
    +
  • all — Show all edge kinds.
    • +
  • normal — Show normal dependencies.
    • +
  • build — Show build dependencies.
    • +
  • dev — Show development dependencies.
    • +
  • features — Show features enabled by each dependency. If this is the only +kind given, then it will automatically include the other dependency kinds.
    • +
  • no-normal — Do not include normal dependencies.
    • +
  • no-build — Do not include build dependencies.
    • +
  • no-dev — Do not include development dependencies.
    • +
+

The no- prefixed options cannot be mixed with the other dependency kinds.

+

The default is normal,build,dev.

+ + +
--target triple
+
Filter dependencies matching the given target-triple. The default is the host +platform. Use the value all to include all targets.
+ + +
+ +### Tree Formatting Options + +
+ +
--charset charset
+
Chooses the character set to use for the tree. Valid values are "utf8" or +"ascii". Default is "utf8".
+ + +
-f format
+
--format format
+
Set the format string for each package. The default is "{p}".

+

This is an arbitrary string which will be used to display each package. The following +strings will be replaced with the corresponding value:

+
    +
  • {p} — The package name.
    • +
  • {l} — The package license.
    • +
  • {r} — The package repository URL.
    • +
  • {f} — Comma-separated list of package features that are enabled.
    • +
+ + +
--prefix prefix
+
Sets how each line is displayed. The prefix value can be one of:

+
    +
  • indent (default) — Shows each line indented as a tree.
    • +
  • depth — Show as a list, with the numeric depth printed before each entry.
    • +
  • none — Show as a flat list.
    • +
+ + +
+ +### Package Selection + +By default, when no package selection options are given, the packages selected +depend on the selected manifest file (based on the current working directory if +`--manifest-path` is not given). If the manifest is the root of a workspace then +the workspaces default members are selected, otherwise only the package defined +by the manifest will be selected. + +The default members of a workspace can be set explicitly with the +`workspace.default-members` key in the root manifest. If this is not set, a +virtual workspace will include all workspace members (equivalent to passing +`--workspace`), and a non-virtual workspace will include only the root crate itself. + +
+ +
-p spec...
+
--package spec...
+
Display only the specified packages. See cargo-pkgid(1) for the +SPEC format. This flag may be specified multiple times.
+ + +
--workspace
+
Display all members in the workspace.
+ + + + +
--exclude SPEC...
+
Exclude the specified packages. Must be used in conjunction with the +--workspace flag. This flag may be specified multiple times.
+ + +
+ + +### Manifest Options + +
+ +
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Feature Selection + +The feature flags allow you to control the enabled features for the "current" +package. The "current" package is the package in the current directory, or the +one specified in `--manifest-path`. If running in the root of a virtual +workspace, then the default features are selected for all workspace members, +or all features if `--all-features` is specified. + +When no feature options are given, the `default` feature is activated for +every selected package. + +
+ +
--features features
+
Space or comma separated list of features to activate. These features only +apply to the current directory's package. Features of direct dependencies +may be enabled with <dep-name>/<feature-name> syntax. This flag may be +specified multiple times, which enables all specified features.
+ + +
--all-features
+
Activate all available features of all selected packages.
+ + +
--no-default-features
+
Do not activate the default feature of the 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.

+ + + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Display the tree for the package in the current directory: + + cargo tree + +2. Display all the packages that depend on the `syn` package: + + cargo tree -i syn + +3. Show the features enabled on each package: + + cargo tree --format "{p} {f}" + +4. Show all packages that are built multiple times. This can happen if multiple + semver-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). + + cargo tree -d + +5. Explain why features are enabled for the `syn` package: + + cargo tree -e features -i syn + + The `-e features` flag is used to show features. The `-i` flag is used to + invert the graph so that it displays the packages that depend on `syn`. An + example of what this would display: + + ``` + syn v1.0.17 + ├── syn feature "clone-impls" + │ └── syn feature "default" + │ └── rustversion v1.0.2 + │ └── rustversion feature "default" + │ └── myproject v0.1.0 (/myproject) + │ └── myproject feature "default" (command-line) + ├── syn feature "default" (*) + ├── syn feature "derive" + │ └── syn feature "default" (*) + ├── syn feature "full" + │ └── rustversion v1.0.2 (*) + ├── syn feature "parsing" + │ └── syn feature "default" (*) + ├── syn feature "printing" + │ └── syn feature "default" (*) + ├── syn feature "proc-macro" + │ └── syn feature "default" (*) + └── syn feature "quote" + ├── syn feature "printing" (*) + └── syn feature "proc-macro" (*) + ``` + + To read this graph, you can follow the chain for each feature from the root + to see why it is included. For example, the "full" feature is added by the + `rustversion` crate which is included from `myproject` (with the default + features), and `myproject` is the package selected on the command-line. All + of the other `syn` features are added by the "default" feature ("quote" is + added by "printing" and "proc-macro", both of which are default features). + + If you're having difficulty cross-referencing the de-duplicated `(*)` + entries, try with the `--no-dedupe` flag to get the full output. + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-metadata(1)](cargo-metadata.md) diff --git a/src/doc/src/commands/cargo-uninstall.md b/src/doc/src/commands/cargo-uninstall.md index 971ad3435df..36186f03ef8 100644 --- a/src/doc/src/commands/cargo-uninstall.md +++ b/src/doc/src/commands/cargo-uninstall.md @@ -1,3 +1,125 @@ -# cargo uninstall -{{#include command-common.html}} -{{#include ../../man/generated/cargo-uninstall.html}} +# cargo-uninstall(1) + +## NAME + +cargo-uninstall - Remove a Rust binary + +## SYNOPSIS + +`cargo uninstall` [_options_] [_spec_...] + +## DESCRIPTION + +This command removes a package installed with [cargo-install(1)](cargo-install.md). The _spec_ +argument is a package ID specification of the package to remove (see +[cargo-pkgid(1)](cargo-pkgid.md)). + +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](../reference/config.html) +- `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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-install(1)](cargo-install.md) diff --git a/src/doc/src/commands/cargo-update.md b/src/doc/src/commands/cargo-update.md index 2be849863f3..c07bf49c73b 100644 --- a/src/doc/src/commands/cargo-update.md +++ b/src/doc/src/commands/cargo-update.md @@ -1,3 +1,170 @@ -# cargo update -{{#include command-common.html}} -{{#include ../../man/generated/cargo-update.html}} +# cargo-update(1) + +## NAME + +cargo-update - Update dependencies as recorded in the local lock file + +## SYNOPSIS + +`cargo update` [_options_] + +## DESCRIPTION + +This command will update dependencies in the `Cargo.lock` file to the latest +version. It requires that the `Cargo.lock` file already exists as generated +by commands such as [cargo-build(1)](cargo-build.md) or [cargo-generate-lockfile(1)](cargo-generate-lockfile.md). + +## 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).
+ + +
--dry-run
+
Displays what would be updated, but doesn't actually write the lockfile.
+ + +
+ +### Display Options + +
+
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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. Update only specific dependencies: + + cargo update -p foo -p bar + +3. Set a specific dependency to a specific version: + + cargo update -p foo --precise 1.2.3 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-generate-lockfile(1)](cargo-generate-lockfile.md) diff --git a/src/doc/src/commands/cargo-vendor.md b/src/doc/src/commands/cargo-vendor.md index 1e0f333fe6d..e40e6991579 100644 --- a/src/doc/src/commands/cargo-vendor.md +++ b/src/doc/src/commands/cargo-vendor.md @@ -1,4 +1,175 @@ -# cargo vendor -{{#include command-common.html}} -{{#include ../../man/generated/cargo-vendor.html}} +# cargo-vendor(1) + +## NAME + +cargo-vendor - Vendor all dependencies locally + +## SYNOPSIS + +`cargo vendor` [_options_] [_path_] + +## DESCRIPTION + +This cargo subcommand will vendor all crates.io and git dependencies for a +project into the specified directory at ``. After this command completes +the vendor directory specified by `` will contain all remote sources from +dependencies specified. Additional manifests beyond the default one can be +specified with the `-s` option. + +The `cargo vendor` command will also print out the configuration necessary +to use the vendored sources, which you will need to add to `.cargo/config.toml`. + +## OPTIONS + +### Vendor Options + +
+ +
-s manifest
+
--sync manifest
+
Specify extra Cargo.toml manifests to workspaces which should also be +vendored and synced to the output.
+ + +
--no-delete
+
Don't delete the "vendor" directory when vendoring, but rather keep all +existing contents of the vendor directory
+ + +
--respect-source-config
+
Instead of ignoring [source] configuration by default in .cargo/config.toml +read it and use it when downloading crates from crates.io, for example
+ + +
--versioned-dirs
+
Normally versions are only added to disambiguate multiple versions of the +same package. This option causes all directories in the "vendor" directory +to be versioned, which makes it easier to track the history of vendored +packages over time, and can help with the performance of re-vendoring when +only a subset of the packages have changed.
+ + +
+ +### Manifest Options + +
+ +
--manifest-path path
+
Path to the Cargo.toml file. By default, Cargo searches for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### 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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) for +details on environment variables that Cargo reads. + + +## EXIT STATUS + +* `0`: Cargo succeeded. +* `101`: Cargo failed to complete. + + +## EXAMPLES + +1. Vendor all dependencies into a local "vendor" folder + + cargo vendor + +2. Vendor all dependencies into a local "third-party/vendor" folder + + cargo vendor third-party/vendor + +3. Vendor the current workspace as well as another to "vendor" + + cargo vendor -s ../path/to/Cargo.toml + +## SEE ALSO +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-verify-project.md b/src/doc/src/commands/cargo-verify-project.md index 4a4c7668267..35a39787aa5 100644 --- a/src/doc/src/commands/cargo-verify-project.md +++ b/src/doc/src/commands/cargo-verify-project.md @@ -1,3 +1,135 @@ -# cargo verify-project -{{#include command-common.html}} -{{#include ../../man/generated/cargo-verify-project.html}} +# cargo-verify-project(1) + +## NAME + +cargo-verify-project - Check correctness of crate manifest + +## SYNOPSIS + +`cargo verify-project` [_options_] + +## DESCRIPTION + +This command will parse the local manifest and check its validity. It emits a +JSON object with the result. A successful validation will display: + + {"success":"true"} + +An invalid workspace will display: + + {"invalid":"human-readable error message"} + +## OPTIONS + +### Display Options + +
+ +
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 for the +Cargo.toml file in the current directory or any parent directory.
+ + + +
--frozen
+
--locked
+
Either of these flags requires that the Cargo.lock file is +up-to-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The --frozen flag also prevents Cargo from +attempting to access the network to determine if it is out-of-date.

+

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

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-package(1)](cargo-package.md) diff --git a/src/doc/src/commands/cargo-version.md b/src/doc/src/commands/cargo-version.md index 12833ede4d5..96a3455cd64 100644 --- a/src/doc/src/commands/cargo-version.md +++ b/src/doc/src/commands/cargo-version.md @@ -1,3 +1,42 @@ -# cargo version -{{#include command-common.html}} -{{#include ../../man/generated/cargo-version.html}} +# cargo-version(1) + +## NAME + +cargo-version - Show version information + +## SYNOPSIS + +`cargo version` [_options_] + +## DESCRIPTION + +Displays the version of Cargo. + +## OPTIONS + +
+ +
-v
+
--verbose
+
Display additional version information.
+ + +
+ +## EXAMPLES + +1. Display the version: + + cargo version + +2. The version is also available via flags: + + cargo --version + cargo -V + +3. Display extra version information: + + cargo -Vv + +## SEE ALSO +[cargo(1)](cargo.md) diff --git a/src/doc/src/commands/cargo-yank.md b/src/doc/src/commands/cargo-yank.md index d6ca7b3c6fd..fea02c57707 100644 --- a/src/doc/src/commands/cargo-yank.md +++ b/src/doc/src/commands/cargo-yank.md @@ -1,3 +1,143 @@ -# cargo yank -{{#include command-common.html}} -{{#include ../../man/generated/cargo-yank.html}} +# cargo-yank(1) + +## 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)](cargo-login.md). + +If the crate name is not specified, it will use the package name from the +current directory. + +## OPTIONS + +### Yank Options + +
+ +
--vers version
+
The version to yank or un-yank.
+ + +
--undo
+
Undo a yank, putting a version back into the index.
+ + +
--token token
+
API token to use when authenticating. This overrides the token stored in +the credentials file (which is created by cargo-login(1)).

+

Cargo config environment variables can be +used to override the tokens stored in the credentials file. The token for +crates.io may be specified with the CARGO_REGISTRY_TOKEN environment +variable. Tokens for other registries may be specified with environment +variables of the form CARGO_REGISTRIES_NAME_TOKEN where NAME is the name +of the registry in all capital letters.

+ + + +
--index index
+
The URL of the registry index to use.
+ + + +
--registry registry
+
Name of the registry to use. Registry names are defined in Cargo config +files. If not specified, the default registry is used, +which is defined by the registry.default config key which defaults to +crates-io.
+ + + +
+ +### Display Options + +
+ +
-v
+
--verbose
+
Use verbose output. May be specified twice for "very verbose" output which +includes extra output such as dependency warnings and build script output. +May also be specified with the term.verbose +config value.
+ + +
-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 + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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 + +## SEE ALSO +[cargo(1)](cargo.md), [cargo-login(1)](cargo-login.md), [cargo-publish(1)](cargo-publish.md) diff --git a/src/doc/src/commands/cargo.md b/src/doc/src/commands/cargo.md index a9ef0a2d231..007c87a18fe 100644 --- a/src/doc/src/commands/cargo.md +++ b/src/doc/src/commands/cargo.md @@ -1,3 +1,311 @@ -# cargo -{{#include command-common.html}} -{{#include ../../man/generated/cargo.html}} +# cargo(1) + +## NAME + +cargo - The Rust package manager + +## SYNOPSIS + +`cargo` [_options_] _command_ [_args_]\ +`cargo` [_options_] `--version`\ +`cargo` [_options_] `--list`\ +`cargo` [_options_] `--help`\ +`cargo` [_options_] `--explain` _code_ + +## DESCRIPTION + +This program is a package manager and build tool for the Rust language, +available at . + +## COMMANDS + +### Build Commands + +[cargo-bench(1)](cargo-bench.md)\ +    Execute benchmarks of a package. + +[cargo-build(1)](cargo-build.md)\ +    Compile a package. + +[cargo-check(1)](cargo-check.md)\ +    Check a local package and all of its dependencies for errors. + +[cargo-clean(1)](cargo-clean.md)\ +    Remove artifacts that Cargo has generated in the past. + +[cargo-doc(1)](cargo-doc.md)\ +    Build a package's documentation. + +[cargo-fetch(1)](cargo-fetch.md)\ +    Fetch dependencies of a package from the network. + +[cargo-fix(1)](cargo-fix.md)\ +    Automatically fix lint warnings reported by rustc. + +[cargo-run(1)](cargo-run.md)\ +    Run a binary or example of the local package. + +[cargo-rustc(1)](cargo-rustc.md)\ +    Compile a package, and pass extra options to the compiler. + +[cargo-rustdoc(1)](cargo-rustdoc.md)\ +    Build a package's documentation, using specified custom flags. + +[cargo-test(1)](cargo-test.md)\ +    Execute unit and integration tests of a package. + +### Manifest Commands + +[cargo-generate-lockfile(1)](cargo-generate-lockfile.md)\ +    Generate `Cargo.lock` for a project. + +[cargo-locate-project(1)](cargo-locate-project.md)\ +    Print a JSON representation of a `Cargo.toml` file's location. + +[cargo-metadata(1)](cargo-metadata.md)\ +    Output the resolved dependencies of a package in machine-readable format. + +[cargo-pkgid(1)](cargo-pkgid.md)\ +    Print a fully qualified package specification. + +[cargo-tree(1)](cargo-tree.md)\ +    Display a tree visualization of a dependency graph. + +[cargo-update(1)](cargo-update.md)\ +    Update dependencies as recorded in the local lock file. + +[cargo-vendor(1)](cargo-vendor.md)\ +    Vendor all dependencies locally. + +[cargo-verify-project(1)](cargo-verify-project.md)\ +    Check correctness of crate manifest. + +### Package Commands + +[cargo-init(1)](cargo-init.md)\ +    Create a new Cargo package in an existing directory. + +[cargo-install(1)](cargo-install.md)\ +    Build and install a Rust binary. + +[cargo-new(1)](cargo-new.md)\ +    Create a new Cargo package. + +[cargo-search(1)](cargo-search.md)\ +    Search packages in crates.io. + +[cargo-uninstall(1)](cargo-uninstall.md)\ +    Remove a Rust binary. + +### Publishing Commands + +[cargo-login(1)](cargo-login.md)\ +    Save an API token from the registry locally. + +[cargo-owner(1)](cargo-owner.md)\ +    Manage the owners of a crate on the registry. + +[cargo-package(1)](cargo-package.md)\ +    Assemble the local package into a distributable tarball. + +[cargo-publish(1)](cargo-publish.md)\ +    Upload a package to the registry. + +[cargo-yank(1)](cargo-yank.md)\ +    Remove a pushed crate from the index. + +### General Commands + +[cargo-help(1)](cargo-help.md)\ +    Display help information about Cargo. + +[cargo-version(1)](cargo-version.md)\ +    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.

+ + +
--offline
+
Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible.

+

Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the cargo-fetch(1) command to download dependencies before going +offline.

+

May also be specified with the net.offline config value.

+ + +
+ +### Common Options + +
+ +
+toolchain
+
If Cargo has been installed with rustup, and the first argument to cargo +begins with +, it will be interpreted as a rustup toolchain name (such +as +stable or +nightly). +See the rustup documentation +for more information about how toolchain overrides work.
+ + +
-h
+
--help
+
Prints help information.
+ + +
-Z flag
+
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
+ + +
+ + +## ENVIRONMENT + +See [the reference](../reference/environment-variables.html) 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)](cargo-install.md) will be located here. If using +rustup, executables distributed with Rust are also located here. + +`$CARGO_HOME/config.toml`\ +    The global configuration file. See [the reference](../reference/config.html) +for more information about configuration files. + +`.cargo/config.toml`\ +    Cargo automatically searches for a file named `.cargo/config.toml` in the +current directory, and all parent directories. These configuration files +will be merged with the global configuration file. + +`$CARGO_HOME/credentials.toml`\ +    Private authentication information for logging in to a registry. + +`$CARGO_HOME/registry/`\ +    This directory contains cached downloads of the registry index and any +downloaded dependencies. + +`$CARGO_HOME/git/`\ +    This directory contains cached downloads of git dependencies. + +Please note that the internal structure of the `$CARGO_HOME` directory is not +stable yet and may be subject to change. + +## EXAMPLES + +1. Build a local package and all of its dependencies: + + cargo build + +2. Build a package with optimizations: + + cargo build --release + +3. Run tests for a cross-compiled target: + + cargo test --target i686-unknown-linux-gnu + +4. Create a new package that builds an executable: + + cargo new foobar + +5. Create a package in the current directory: + + mkdir foo && cd foo + cargo init . + +6. Learn about a command's options and usage: + + cargo help clean + +## BUGS + +See for issues. + +## SEE ALSO +[rustc(1)](https://doc.rust-lang.org/rustc/index.html), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) diff --git a/src/etc/man/cargo-bench.1 b/src/etc/man/cargo-bench.1 index b17bb536dc9..e23d25268d6 100644 --- a/src/etc/man/cargo-bench.1 +++ b/src/etc/man/cargo-bench.1 @@ -1,488 +1,356 @@ '\" t -.\" Title: cargo-bench -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-BENCH" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-BENCH" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-bench \- Execute benchmarks of a package .SH "SYNOPSIS" -.sp -\fBcargo bench [\fIOPTIONS\fP] [BENCHNAME] [\-\- \fIBENCH\-OPTIONS\fP]\fP +\fBcargo bench\fR [\fIoptions\fR] [\fIbenchname\fR] [\fB\-\-\fR \fIbench\-options\fR] .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 \-\- \-\-help\fP. As an example, this will -run only the benchmark named \fBfoo\fP (and skip other similarly named benchmarks -like \fBfoobar\fP): +The benchmark filtering argument \fIbenchname\fR and all the arguments following +the two dashes (\fB\-\-\fR) are passed to the benchmark binaries and thus to +\fIlibtest\fR (rustc's built in unit\-test and micro\-benchmarking framework). If +you are passing arguments to both Cargo and the binary, the ones after \fB\-\-\fR go +to the binary, the ones before go to Cargo. For details about libtest's +arguments see the output of \fBcargo bench \-\- \-\-help\fR\&. As an example, this will +run only the benchmark named \fBfoo\fR (and skip other similarly named benchmarks +like \fBfoobar\fR): .sp -.if n .RS 4 +.RS 4 .nf cargo bench \-\- foo \-\-exact .fi -.if n .RE +.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. Cargo passes the \fB\-\-bench\fP flag to +Benchmarks are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an +executable with a \fBmain\fR function that automatically runs all functions +annotated with the \fB#[bench]\fR attribute. Cargo passes the \fB\-\-bench\fR flag to the test harness to tell it to run only benchmarks. .sp -The libtest harness may be disabled by setting \fBharness = false\fP in the target -manifest settings, in which case your code will need to provide its own \fBmain\fP +The libtest harness may be disabled by setting \fBharness = false\fR in the target +manifest settings, in which case your code will need to provide its own \fBmain\fR function to handle running benchmarks. .RS 3 -.ll -.6i +.ll -5 .sp -\fBNote\fP: The -\c -.URL "https://doc.rust\-lang.org/nightly/unstable\-book/library\-features/test.html" "\fB#[bench]\fP attribute" +\fBNote\fR: The +\fI\f(BI#[bench]\fI attribute\fR is currently unstable and only available on the -.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel" "." +\fInightly channel\fR \&. There are some packages available on -.URL "https://crates.io/keywords/benchmark" "crates.io" " " -that may help with +\fIcrates.io\fR that may help with running benchmarks on the stable channel, such as -.URL "https://crates.io/crates/criterion" "Criterion" "." +\fICriterion\fR \&. .br .RE .ll .SH "OPTIONS" .SS "Benchmark Options" .sp -\fB\-\-no\-run\fP +\fB\-\-no\-run\fR .RS 4 -Compile, but don\(cqt run benchmarks. +Compile, but don't run benchmarks. .RE .sp -\fB\-\-no\-fail\-fast\fP +\fB\-\-no\-fail\-fast\fR .RS 4 Run all benchmarks regardless of failure. Without this flag, Cargo will exit -after the first executable fails. The Rust test harness will run all -benchmarks within the executable to completion, this flag only applies to -the executable as a whole. +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 selected manifest file (based on the current working directory if -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Benchmark only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Benchmark only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Benchmark all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR 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 +When no target selection options are given, \fBcargo bench\fR 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 +\h'-04'\(bu\h'+02'lib \[em] 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 +\h'-04'\(bu\h'+02'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 +\h'-04'\(bu\h'+02'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 +\h'-04'\(bu\h'+02'bins as benchmarks .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -benchmark targets +\h'-04'\(bu\h'+02'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 +The default behavior can be changed by setting the \fBbench\fR flag for the target +in the manifest settings. Setting examples to \fBbench = true\fR will build and +run the example as a benchmark. Setting targets to \fBbench = false\fR will stop them from being benchmarked by default. Target selection options that take a -target by name ignore the \fBbench\fP flag and will always benchmark the given +target by name ignore the \fBbench\fR flag and will always benchmark the given target. .sp -Passing target selection flags will benchmark only the -specified targets. +Passing target selection flags will benchmark only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Benchmark the package\(cqs library. +Benchmark the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Benchmark the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Benchmark all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Benchmark the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Benchmark all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Benchmark the specified integration test. This flag may be specified multiple -times. +Benchmark the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Benchmark all targets in test mode that have the \fBtest = true\fP manifest +Benchmark all targets in test mode that have the \fBtest = true\fR manifest flag set. By default this includes the library and binaries built as unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Benchmark the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Benchmark all targets in benchmark mode that have the \fBbench = true\fP +Benchmark all targets in benchmark mode that have the \fBbench = true\fR manifest flag set. By default this includes the library and binaries built as benchmarks, and bench targets. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Benchmark all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Benchmark all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Benchmark for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR 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: +passing \fB\-\-nocapture\fR to the benchmark binaries: .sp -.if n .RS 4 +.RS 4 .nf cargo bench \-\- \-\-nocapture .fi -.if n .RE +.RE .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -492,117 +360,91 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" -.sp -The \fB\-\-jobs\fP argument affects the building of the benchmark executable but +The \fB\-\-jobs\fR argument affects the building of the benchmark executable but does not affect how many threads are used when running the benchmarks. The Rust test harness runs benchmarks serially in a single thread. .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" +\fIthe reference\fR 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. +Benchmarks are always built with the \fBbench\fR profile. Binary and lib targets +are built separately as benchmarks with the \fBbench\fR profile. Library targets +are built with the \fBrelease\fR profiles when linked to binaries and benchmarks. +Dependencies use the \fBrelease\fR 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 +\fBcargo\-build\fR(1) which will use the \fBtest\fR 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 +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Build and execute all the benchmarks of the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo bench .fi -.if n .RE +.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: +\h'-04' 2.\h'+01'Run only a specific benchmark within a specific benchmark target: .sp -.if n .RS 4 +.RS 4 .nf cargo bench \-\-bench bench_name \-\- modname::some_benchmark .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-test\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-test\fR(1) diff --git a/src/etc/man/cargo-build.1 b/src/etc/man/cargo-build.1 index 6c331075f80..7cc100ea2b8 100644 --- a/src/etc/man/cargo-build.1 +++ b/src/etc/man/cargo-build.1 @@ -1,395 +1,296 @@ '\" t -.\" Title: cargo-build -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-BUILD" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-BUILD" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-build \- Compile the current package .SH "SYNOPSIS" -.sp -\fBcargo build [\fIOPTIONS\fP]\fP +\fBcargo build\fR [\fIoptions\fR] .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 selected manifest file (based on the current working directory if -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Build only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Build only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Build all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR 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 +When no target selection options are given, \fBcargo build\fR will build all binary and library targets of the selected packages. Binaries are skipped if -they have \fBrequired\-features\fP that are missing. +they have \fBrequired\-features\fR that are missing. .sp -Passing target selection flags will build only the -specified targets. +Passing target selection flags will build only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Build the package\(cqs library. +Build the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Build the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Build all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Build the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Build all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Build the specified integration test. This flag may be specified multiple -times. +Build the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Build all targets in test mode that have the \fBtest = true\fP manifest +Build all targets in test mode that have the \fBtest = true\fR manifest flag set. By default this includes the library and binaries built as unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Build the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Build all targets in benchmark mode that have the \fBbench = true\fP +Build all targets in benchmark mode that have the \fBbench = true\fR manifest flag set. By default this includes the library and binaries built as benchmarks, and bench targets. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Build for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Build optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Build optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .sp -\fB\-\-out\-dir\fP \fIDIRECTORY\fP +\fB\-\-out\-dir\fR \fIdirectory\fR .RS 4 Copy final artifacts to this directory. .sp This option is unstable and available only on the -\c -.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel" -and requires the \fB\-Z unstable\-options\fP flag to enable. -See \c -.URL "https://github.com/rust\-lang/cargo/issues/6790" "" " " -for more information. +\fInightly channel\fR +and requires the \fB\-Z unstable\-options\fR flag to enable. +See https://github.com/rust\-lang/cargo/issues/6790 for more information. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .sp -\fB\-\-build\-plan\fP +\fB\-\-build\-plan\fR .RS 4 -Outputs a series of JSON messages to stdout that indicate the commands to -run the build. +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 -\c -.URL "https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html" "nightly channel" -and requires the \fB\-Z unstable\-options\fP flag to enable. -See \c -.URL "https://github.com/rust\-lang/cargo/issues/5579" "" " " -for more information. +\fInightly channel\fR +and requires the \fB\-Z unstable\-options\fR flag to enable. +See for more information. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -399,146 +300,110 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Build the local package and all of its dependencies: .sp -.if n .RS 4 +.RS 4 .nf cargo build .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Build with optimizations: +\h'-04' 2.\h'+01'Build with optimizations: .sp -.if n .RS 4 +.RS 4 .nf cargo build \-\-release .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-rustc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-rustc\fR(1) diff --git a/src/etc/man/cargo-check.1 b/src/etc/man/cargo-check.1 index d31221204e0..d984658e474 100644 --- a/src/etc/man/cargo-check.1 +++ b/src/etc/man/cargo-check.1 @@ -1,381 +1,288 @@ '\" t -.\" Title: cargo-check -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-CHECK" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-CHECK" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-check \- Check the current package .SH "SYNOPSIS" -.sp -\fBcargo check [\fIOPTIONS\fP]\fP +\fBcargo check\fR [\fIoptions\fR] .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 +generation, which is faster than running \fBcargo build\fR\&. The compiler will save metadata files to disk so that future runs will reuse them if the source has not been modified. .SH "OPTIONS" .SS "Package Selection" -.sp By default, when no package selection options are given, the packages selected depend on the selected manifest file (based on the current working directory if -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Check only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Check only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Check all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR 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 +When no target selection options are given, \fBcargo check\fR will check all binary and library targets of the selected packages. Binaries are skipped if -they have \fBrequired\-features\fP that are missing. +they have \fBrequired\-features\fR that are missing. .sp -Passing target selection flags will check only the -specified targets. +Passing target selection flags will check only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Check the package\(cqs library. +Check the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Check the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Check all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Check the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Check all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Check the specified integration test. This flag may be specified multiple -times. +Check the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Check all targets in test mode that have the \fBtest = true\fP manifest +Check all targets in test mode that have the \fBtest = true\fR manifest flag set. By default this includes the library and binaries built as unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Check the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Check all targets in benchmark mode that have the \fBbench = true\fP +Check all targets in benchmark mode that have the \fBbench = true\fR manifest flag set. By default this includes the library and binaries built as benchmarks, and bench targets. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Check all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Check all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Check for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Check optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Check optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .sp -\fB\-\-profile\fP \fINAME\fP +\fB\-\-profile\fR \fIname\fR .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. +Changes check behavior. Currently only \fBtest\fR is supported, +which will check with the \fB#[cfg(test)]\fR attribute enabled. +This is useful to have it check unit tests which are usually +excluded via the \fBcfg\fR attribute. This does not change the actual profile +used. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -385,146 +292,110 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Check the local package for errors: .sp -.if n .RS 4 +.RS 4 .nf cargo check .fi -.if n .RE +.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: +\h'-04' 2.\h'+01'Check all targets, including unit tests: .sp -.if n .RS 4 +.RS 4 .nf cargo check \-\-all\-targets \-\-profile=test .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-clean.1 b/src/etc/man/cargo-clean.1 index 084866f7624..c9112bb0564 100644 --- a/src/etc/man/cargo-clean.1 +++ b/src/etc/man/cargo-clean.1 @@ -1,170 +1,122 @@ '\" t -.\" Title: cargo-clean -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-CLEAN" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-CLEAN" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-clean \- Remove generated artifacts .SH "SYNOPSIS" -.sp -\fBcargo clean [\fIOPTIONS\fP]\fP +\fBcargo clean\fR [\fIoptions\fR] .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. +With no options, \fBcargo clean\fR 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... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 Clean only the specified packages. This flag may be specified -multiple times. See \fBcargo\-pkgid\fP(1) for the SPEC format. +multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format. .RE .SS "Clean Options" .sp -\fB\-\-doc\fP +\fB\-\-doc\fR .RS 4 -This option will cause \fBcargo clean\fP to remove only the \fBdoc\fP directory in +This option will cause \fBcargo clean\fR to remove only the \fBdoc\fR directory in the target directory. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Clean all artifacts that were built with the \fBrelease\fP or \fBbench\fP -profiles. +Clean all artifacts that were built with the \fBrelease\fR or \fBbench\fR profiles. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Clean for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -174,86 +126,64 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Remove the entire target directory: .sp -.if n .RS 4 +.RS 4 .nf cargo clean .fi -.if n .RE +.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: +\h'-04' 2.\h'+01'Remove only the release artifacts: .sp -.if n .RS 4 +.RS 4 .nf cargo clean \-\-release .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-doc.1 b/src/etc/man/cargo-doc.1 index 136e689b08b..93e1534a595 100644 --- a/src/etc/man/cargo-doc.1 +++ b/src/etc/man/cargo-doc.1 @@ -1,340 +1,247 @@ '\" t -.\" Title: cargo-doc -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-04-21 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-DOC" "1" "2020-04-21" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-DOC" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" -cargo\-doc \- Build a package\(aqs documentation +cargo\-doc \- Build a package's documentation .SH "SYNOPSIS" -.sp -\fBcargo doc [\fIOPTIONS\fP]\fP +\fBcargo doc\fR [\fIoptions\fR] .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. +is placed in \fBtarget/doc\fR in rustdoc's usual format. .SH "OPTIONS" .SS "Documentation Options" .sp -\fB\-\-open\fP +\fB\-\-open\fR .RS 4 Open the docs in a browser after building them. This will use your default -browser unless you define another one in the \fBBROWSER\fP environment -variable. +browser unless you define another one in the \fBBROWSER\fR environment variable. .RE .sp -\fB\-\-no\-deps\fP +\fB\-\-no\-deps\fR .RS 4 Do not build documentation for dependencies. .RE .sp -\fB\-\-document\-private\-items\fP +\fB\-\-document\-private\-items\fR .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 selected manifest file (based on the current working directory if -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Document only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Document only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Document all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR 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 +When no target selection options are given, \fBcargo doc\fR will document all binary and library targets of the selected package. The binary will be skipped if its name is the same as the lib target. Binaries are skipped if they have -\fBrequired\-features\fP that are missing. +\fBrequired\-features\fR 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 +The default behavior can be changed by setting \fBdoc = false\fR for the target in +the manifest settings. Using target selection options will ignore the \fBdoc\fR flag and will always document the given target. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Document the package\(cqs library. +Document the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Document the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Document all binary targets. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Document for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Document optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Document optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -344,130 +251,101 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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. +\h'-04' 1.\h'+01'Build the local package documentation and its dependencies and output to +\fBtarget/doc\fR\&. .sp -.if n .RS 4 +.RS 4 .nf cargo doc .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-rustdoc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-rustdoc\fR(1), \fBrustdoc\fR(1) diff --git a/src/etc/man/cargo-fetch.1 b/src/etc/man/cargo-fetch.1 index 0a4225de40e..b2e798ec31b 100644 --- a/src/etc/man/cargo-fetch.1 +++ b/src/etc/man/cargo-fetch.1 @@ -1,148 +1,101 @@ '\" t -.\" Title: cargo-fetch -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-11-11 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-FETCH" "1" "2019-11-11" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-FETCH" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-fetch \- Fetch dependencies of a package from the network .SH "SYNOPSIS" -.sp -\fBcargo fetch [\fIOPTIONS\fP]\fP +\fBcargo fetch\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -If a \fBCargo.lock\fP file is available, this command will ensure that all of the +If a \fBCargo.lock\fR file is available, this command will ensure that all of the git dependencies and/or registry dependencies are downloaded and locally -available. Subsequent Cargo commands never touch the network after a \fBcargo -fetch\fP unless the lock file changes. +available. Subsequent Cargo commands never touch the network after a \fBcargo fetch\fR unless the lock file changes. .sp If the lock file is not available, then this command will generate the lock file before fetching the dependencies. .sp -If \fB\-\-target\fP is not specified, then all target dependencies are fetched. +If \fB\-\-target\fR is not specified, then all target dependencies are fetched. .sp -See also the \c -.URL "https://crates.io/crates/cargo\-prefetch" "cargo\-prefetch" +See also the \fIcargo\-prefetch\fR plugin which adds a command to download popular crates. This may be useful if -you plan to use Cargo without a network with the \fB\-\-offline\fP flag. +you plan to use Cargo without a network with the \fB\-\-offline\fR flag. .SH "OPTIONS" .SS "Fetch options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Fetch for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -152,69 +105,54 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Fetch all dependencies: .sp -.if n .RS 4 +.RS 4 .nf cargo fetch .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-update\fP(1), \fBcargo\-generate\-lockfile\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-update\fR(1), \fBcargo\-generate\-lockfile\fR(1) diff --git a/src/etc/man/cargo-fix.1 b/src/etc/man/cargo-fix.1 index 9a29b4a0048..6df87b542b7 100644 --- a/src/etc/man/cargo-fix.1 +++ b/src/etc/man/cargo-fix.1 @@ -1,455 +1,362 @@ '\" t -.\" Title: cargo-fix -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-FIX" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-FIX" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-fix \- Automatically fix lint warnings reported by rustc .SH "SYNOPSIS" -.sp -\fBcargo fix [\fIOPTIONS\fP]\fP +\fBcargo fix\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This Cargo subcommand will automatically take rustc\(cqs suggestions from +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 \fBcargo fix\fP subcommand is also being developed for the Rust 2018 edition +The \fBcargo fix\fR 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 +Executing \fBcargo fix\fR will under the hood execute \fBcargo\-check\fR(1). Any warnings applicable to your crate will be automatically fixed (if possible) and all remaining warnings will be displayed when the check process is finished. For -example if you\(cqd like to prepare for the 2018 edition, you can do so by +example if you'd like to prepare for the 2018 edition, you can do so by executing: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition .fi -.if n .RE +.RE .sp -which behaves the same as \fBcargo check \-\-all\-targets\fP. +which behaves the same as \fBcargo check \-\-all\-targets\fR\&. .sp -\fBcargo fix\fP is only capable of fixing code that is normally compiled with -\fBcargo check\fP. If code is conditionally enabled with optional features, you +\fBcargo fix\fR is only capable of fixing code that is normally compiled with +\fBcargo check\fR\&. If code is conditionally enabled with optional features, you will need to enable those features for that code to be analyzed: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition \-\-features foo .fi -.if n .RE +.RE .sp -Similarly, other \fBcfg\fP expressions like platform\-specific code will need to -pass \fB\-\-target\fP to fix code for the given target. +Similarly, other \fBcfg\fR expressions like platform\-specific code will need to +pass \fB\-\-target\fR to fix code for the given target. .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition \-\-target x86_64\-pc\-windows\-gnu .fi -.if n .RE +.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" "" "" +If you encounter any problems with \fBcargo fix\fR or otherwise have any questions +or feature requests please don't hesitate to file an issue at + .SH "OPTIONS" .SS "Fix options" .sp -\fB\-\-broken\-code\fP +\fB\-\-broken\-code\fR .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. +Fix code even if it already has compiler errors. This is useful if \fBcargo fix\fR +fails to apply the changes. It will apply the changes and leave the broken +code in the working directory for you to inspect and manually fix. .RE .sp -\fB\-\-edition\fP +\fB\-\-edition\fR .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 +Apply changes that will update the code to the latest edition. This will not +update the edition in the \fBCargo.toml\fR manifest, which must be updated manually. .RE .sp -\fB\-\-edition\-idioms\fP +\fB\-\-edition\-idioms\fR .RS 4 -Apply suggestions that will update code to the preferred style for the -current edition. +Apply suggestions that will update code to the preferred style for the current +edition. .RE .sp -\fB\-\-allow\-no\-vcs\fP +\fB\-\-allow\-no\-vcs\fR .RS 4 Fix code even if a VCS was not detected. .RE .sp -\fB\-\-allow\-dirty\fP +\fB\-\-allow\-dirty\fR .RS 4 Fix code even if the working directory has changes. .RE .sp -\fB\-\-allow\-staged\fP +\fB\-\-allow\-staged\fR .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 selected manifest file (based on the current working directory if -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Fix only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Fix only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Fix all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Target Selection" +When no target selection options are given, \fBcargo fix\fR will fix all targets +(\fB\-\-all\-targets\fR implied). Binaries are skipped if they have +\fBrequired\-features\fR that are missing. .sp -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. +Passing target selection flags will fix only the specified +targets. .sp -Passing target selection flags will fix only the -specified targets. -.sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Fix the package\(cqs library. +Fix the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Fix the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Fix all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Fix the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Fix all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Fix the specified integration test. This flag may be specified multiple -times. +Fix the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Fix all targets in test mode that have the \fBtest = true\fP manifest +Fix all targets in test mode that have the \fBtest = true\fR manifest flag set. By default this includes the library and binaries built as unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Fix the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Fix all targets in benchmark mode that have the \fBbench = true\fP +Fix all targets in benchmark mode that have the \fBbench = true\fR manifest flag set. By default this includes the library and binaries built as benchmarks, and bench targets. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Fix all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Fix all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Fix for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Fix optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Fix optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .sp -\fB\-\-profile\fP \fINAME\fP +\fB\-\-profile\fR \fIname\fR .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. +Changes fix behavior. Currently only \fBtest\fR is supported, +which will fix with the \fB#[cfg(test)]\fR attribute enabled. +This is useful to have it fix unit tests which are usually +excluded via the \fBcfg\fR attribute. This does not change the actual profile +used. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -459,163 +366,120 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Apply compiler suggestions to the local package: .sp -.if n .RS 4 +.RS 4 .nf cargo fix .fi -.if n .RE +.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: +\h'-04' 2.\h'+01'Convert a 2015 edition to 2018: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition .fi -.if n .RE +.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: +\h'-04' 3.\h'+01'Apply suggested idioms for the current edition: .sp -.if n .RS 4 +.RS 4 .nf cargo fix \-\-edition\-idioms .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-check\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-check\fR(1) diff --git a/src/etc/man/cargo-generate-lockfile.1 b/src/etc/man/cargo-generate-lockfile.1 index 23bb1110b73..8e714a0d5da 100644 --- a/src/etc/man/cargo-generate-lockfile.1 +++ b/src/etc/man/cargo-generate-lockfile.1 @@ -1,123 +1,79 @@ '\" t -.\" Title: cargo-generate-lockfile -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-GENERATE\-LOCKFILE" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-GENERATE\-LOCKFILE" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-generate\-lockfile \- Generate the lockfile for a package .SH "SYNOPSIS" -.sp -\fBcargo generate\-lockfile [\fIOPTIONS\fP]\fP +\fBcargo generate\-lockfile\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This command will create the \fBCargo.lock\fP lockfile for the current package or +This command will create the \fBCargo.lock\fR 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 +See also \fBcargo\-update\fR(1) which is also capable of creating a \fBCargo.lock\fR lockfile and has more options for controlling update behavior. .SH "OPTIONS" .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -127,69 +83,54 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Create or update the lockfile for the current package or workspace: .sp -.if n .RS 4 +.RS 4 .nf cargo generate\-lockfile .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-update\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-update\fR(1) diff --git a/src/etc/man/cargo-help.1 b/src/etc/man/cargo-help.1 index bcff591d531..8ff0ad22e49 100644 --- a/src/etc/man/cargo-help.1 +++ b/src/etc/man/cargo-help.1 @@ -1,75 +1,34 @@ '\" t -.\" Title: cargo-help -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-HELP" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-HELP" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-help \- Get help for a Cargo command .SH "SYNOPSIS" -.sp -\fBcargo help [\fISUBCOMMAND\fP]\fP +\fBcargo help\fR [\fIsubcommand\fR] .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: +\h'-04' 1.\h'+01'Get help for a command: .sp -.if n .RS 4 +.RS 4 .nf cargo help build .fi -.if n .RE +.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: +\h'-04' 2.\h'+01'Help is also available with the \fB\-\-help\fR flag: .sp -.if n .RS 4 +.RS 4 .nf cargo build \-\-help .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) \ No newline at end of file +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-init.1 b/src/etc/man/cargo-init.1 index f1189c74c5f..c0f5f2e8243 100644 --- a/src/etc/man/cargo-init.1 +++ b/src/etc/man/cargo-init.1 @@ -1,374 +1,214 @@ '\" t -.\" Title: cargo-init -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-INIT" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-INIT" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-init \- Create a new Cargo package in an existing directory .SH "SYNOPSIS" -.sp -\fBcargo init [\fIOPTIONS\fP] [\fIPATH\fP]\fP +\fBcargo init\fR [\fIoptions\fR] [\fIpath\fR] .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. +will be used. If not, then a sample \fBsrc/main.rs\fR file will be created, or +\fBsrc/lib.rs\fR if \fB\-\-lib\fR is passed. .sp If the directory is not already in a VCS repository, then a new repository -is created (see \fB\-\-vcs\fP below). +is created (see \fB\-\-vcs\fR 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 +\h'-04'\(bu\h'+02'\fBcargo\-new.name\fR 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 +\h'-04'\(bu\h'+02'\fBCARGO_NAME\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_NAME\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_NAME\fR 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 +\h'-04'\(bu\h'+02'\fBuser.name\fR 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 +\h'-04'\(bu\h'+02'\fBUSER\fR 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 +\h'-04'\(bu\h'+02'\fBUSERNAME\fR 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 +\h'-04'\(bu\h'+02'\fBNAME\fR 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 +\h'-04'\(bu\h'+02'\fBcargo\-new.email\fR 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 +\h'-04'\(bu\h'+02'\fBCARGO_EMAIL\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_EMAIL\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_EMAIL\fR 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 +\h'-04'\(bu\h'+02'\fBuser.email\fR 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 +\h'-04'\(bu\h'+02'\fBEMAIL\fR environment variable .RE .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" " " -for more information about +See \fIthe reference\fR for more information about configuration files. .sp -See \fBcargo\-new\fP(1) for a similar command which will create a new package in +See \fBcargo\-new\fR(1) for a similar command which will create a new package in a new directory. .SH "OPTIONS" .SS "Init Options" .sp -\fB\-\-bin\fP +\fB\-\-bin\fR .RS 4 -Create a package with a binary target (\fBsrc/main.rs\fP). +Create a package with a binary target (\fBsrc/main.rs\fR). This is the default behavior. .RE .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Create a package with a library target (\fBsrc/lib.rs\fP). +Create a package with a library target (\fBsrc/lib.rs\fR). .RE .sp -\fB\-\-edition\fP \fIEDITION\fP +\fB\-\-edition\fR \fIedition\fR .RS 4 Specify the Rust edition to use. Default is 2018. Possible values: 2015, 2018 .RE .sp -\fB\-\-name\fP \fINAME\fP +\fB\-\-name\fR \fIname\fR .RS 4 Set the package name. Defaults to the directory name. .RE .sp -\fB\-\-vcs\fP \fIVCS\fP +\fB\-\-vcs\fR \fIvcs\fR .RS 4 Initialize a new VCS repository for the given version control system (git, hg, pijul, or fossil) or do not initialize any version control at all -(none). If not specified, defaults to \fBgit\fP or the configuration value -\fBcargo\-new.vcs\fP, or \fBnone\fP if already inside a VCS repository. +(none). If not specified, defaults to \fBgit\fR or the configuration value +\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name +This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name which will restrict publishing only to that registry. .sp -Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry defined by the \fBregistry.default\fP -config key is used. If the default registry is not set and \fB\-\-registry\fP is not -used, the \fBpublish\fP field will not be set which means that publishing will not +Registry names are defined in \fICargo config files\fR \&. +If not specified, the default registry defined by the \fBregistry.default\fR +config key is used. If the default registry is not set and \fB\-\-registry\fR is not +used, the \fBpublish\fR field will not be set which means that publishing will not be restricted. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Create a binary Cargo package in the current directory: .sp -.if n .RS 4 +.RS 4 .nf cargo init .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-new\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-new\fR(1) diff --git a/src/etc/man/cargo-install.1 b/src/etc/man/cargo-install.1 index 7501ddef2f5..10d24e0f606 100644 --- a/src/etc/man/cargo-install.1 +++ b/src/etc/man/cargo-install.1 @@ -1,119 +1,57 @@ '\" t -.\" Title: cargo-install -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-07-01 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-INSTALL" "1" "2020-07-01" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-INSTALL" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-install \- Build and install a Rust binary .SH "SYNOPSIS" -.sp -\fBcargo install [\fIOPTIONS\fP] \fICRATE\fP...\fP +\fBcargo install\fR [\fIoptions\fR] \fIcrate\fR\&... .br -\fBcargo install [\fIOPTIONS\fP] \-\-path \fIPATH\fP\fP +\fBcargo install\fR [\fIoptions\fR] \fB\-\-path\fR \fIpath\fR .br -\fBcargo install [\fIOPTIONS\fP] \-\-git \fIURL\fP [\fICRATE\fP...]\fP +\fBcargo install\fR [\fIoptions\fR] \fB\-\-git\fR \fIurl\fR [\fIcrate\fR\&...] .br -\fBcargo install [\fIOPTIONS\fP] \-\-list\fP +\fBcargo install\fR [\fIoptions\fR] \fB\-\-list\fR .SH "DESCRIPTION" -.sp -This command manages Cargo\(cqs local set of installed binary crates. Only -packages which have executable \fB[[bin]]\fP or \fB[[example]]\fP targets can be -installed, and all executables are installed into the installation root\(cqs -\fBbin\fP folder. +This command manages Cargo's local set of installed binary crates. Only +packages which have executable \fB[[bin]]\fR or \fB[[example]]\fR targets can be +installed, and all executables are installed into the installation root's +\fBbin\fR 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 +\h'-04'\(bu\h'+02'\fB\-\-root\fR 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 +\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR 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" "" +\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_HOME\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR 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 +\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR .RE .sp There are multiple sources from which a crate can be installed. The default -location is crates.io but the \fB\-\-git\fP, \fB\-\-path\fP, and \fB\-\-registry\fP flags can +location is crates.io but the \fB\-\-git\fR, \fB\-\-path\fR, and \fB\-\-registry\fR flags can change this source. If the source contains more than one package (such as -crates.io or a git repository with multiple crates) the \fICRATE\fP argument is +crates.io or a git repository with multiple crates) the \fIcrate\fR argument is required to indicate which crate should be installed. .sp Crates from crates.io can optionally specify the version they wish to install -via the \fB\-\-version\fP flags, and similarly packages from git repositories can +via the \fB\-\-version\fR flags, and similarly packages from git repositories can optionally specify the branch, tag, or revision that should be installed. If a -crate has multiple binaries, the \fB\-\-bin\fP argument can selectively install only -one of them, and if you\(cqd rather install examples the \fB\-\-example\fP argument can +crate has multiple binaries, the \fB\-\-bin\fR argument can selectively install only +one of them, and if you'd rather install examples the \fB\-\-example\fR argument can be used as well. .sp If the package is already installed, Cargo will reinstall it if the installed @@ -121,259 +59,220 @@ version does not appear to be up\-to\-date. If any of the following values change, then Cargo will reinstall the package: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The package version and source. +\h'-04'\(bu\h'+02'The package version and source. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The set of binary names installed. +\h'-04'\(bu\h'+02'The set of binary names installed. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The chosen features. +\h'-04'\(bu\h'+02'The chosen features. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The release mode (\fB\-\-debug\fP). +\h'-04'\(bu\h'+02'The release mode (\fB\-\-debug\fR). .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -The target (\fB\-\-target\fP). +\h'-04'\(bu\h'+02'The target (\fB\-\-target\fR). .RE .sp -Installing with \fB\-\-path\fP will always build and install, unless there are -conflicting binaries from another package. The \fB\-\-force\fP flag may be used to +Installing with \fB\-\-path\fR will always build and install, unless there are +conflicting binaries from another package. The \fB\-\-force\fR flag may be used to force Cargo to always reinstall the package. .sp -If the source is crates.io or \fB\-\-git\fP then by default the crate will be built +If the source is crates.io or \fB\-\-git\fR then by default the crate will be built in a temporary target directory. To avoid this, the target directory can be -specified by setting the \fBCARGO_TARGET_DIR\fP environment variable to a relative +specified by setting the \fBCARGO_TARGET_DIR\fR environment variable to a relative path. In particular, this can be useful for caching build artifacts on continuous integration systems. .sp -By default, the \fBCargo.lock\fP file that is included with the package will be +By default, the \fBCargo.lock\fR file that is included with the package will be ignored. This means that Cargo will recompute which versions of dependencies to use, possibly using newer versions that have been released since the -package was published. The \fB\-\-locked\fP flag can be used to force Cargo to use -the packaged \fBCargo.lock\fP file if it is available. This may be useful for +package was published. The \fB\-\-locked\fR flag can be used to force Cargo to use +the packaged \fBCargo.lock\fR file if it is available. This may be useful for ensuring reproducible builds, to use the exact same set of dependencies that were available when the package was published. It may also be useful if a newer version of a dependency is published that no longer builds on your -system, or has other problems. The downside to using \fB\-\-locked\fP is that you +system, or has other problems. The downside to using \fB\-\-locked\fR is that you will not receive any fixes or updates to any dependency. Note that Cargo did -not start publishing \fBCargo.lock\fP files until version 1.37, which means -packages published with prior versions will not have a \fBCargo.lock\fP file +not start publishing \fBCargo.lock\fR files until version 1.37, which means +packages published with prior versions will not have a \fBCargo.lock\fR file available. .SH "OPTIONS" .SS "Install Options" .sp -\fB\-\-vers\fP \fIVERSION\fP, \fB\-\-version\fP \fIVERSION\fP +\fB\-\-vers\fR \fIversion\fR, +\fB\-\-version\fR \fIversion\fR .RS 4 -Specify a version to install. This may be a -.URL "https://doc.rust\-lang.org/cargo/reference/specifying\-dependencies.md" "version requirement" "," -like -\fB~1.2\fP, to have Cargo select the newest version from the given -requirement. If the version does not have a requirement operator (such as -\fB^\fP or \fB~\fP), then it must be in the form \fIMAJOR.MINOR.PATCH\fP, and will -install exactly that version; it is \fBnot\fP treated as a caret requirement -like Cargo dependencies are. +Specify a version to install. This may be a \fIversion +requirement\fR , like \fB~1.2\fR, to have Cargo +select the newest version from the given requirement. If the version does not +have a requirement operator (such as \fB^\fR or \fB~\fR), then it must be in the form +\fIMAJOR.MINOR.PATCH\fR, and will install exactly that version; it is \fInot\fR +treated as a caret requirement like Cargo dependencies are. .RE .sp -\fB\-\-git\fP \fIURL\fP +\fB\-\-git\fR \fIurl\fR .RS 4 Git URL to install the specified crate from. .RE .sp -\fB\-\-branch\fP \fIBRANCH\fP +\fB\-\-branch\fR \fIbranch\fR .RS 4 Branch to use when installing from git. .RE .sp -\fB\-\-tag\fP \fITAG\fP +\fB\-\-tag\fR \fItag\fR .RS 4 Tag to use when installing from git. .RE .sp -\fB\-\-rev\fP \fISHA\fP +\fB\-\-rev\fR \fIsha\fR .RS 4 Specific commit to use when installing from git. .RE .sp -\fB\-\-path\fP \fIPATH\fP +\fB\-\-path\fR \fIpath\fR .RS 4 Filesystem path to local crate to install. .RE .sp -\fB\-\-list\fP +\fB\-\-list\fR .RS 4 List all installed packages and their versions. .RE .sp -\fB\-f\fP, \fB\-\-force\fP +\fB\-f\fR, +\fB\-\-force\fR .RS 4 -Force overwriting existing crates or binaries. This can be used if a -package has installed a binary with the same name as another package. This -is also useful if something has changed on the system that you want to -rebuild with, such as a newer version of \fBrustc\fP. +Force overwriting existing crates or binaries. This can be used if a package +has installed a binary with the same name as another package. This is also +useful if something has changed on the system that you want to rebuild with, +such as a newer version of \fBrustc\fR\&. .RE .sp -\fB\-\-no\-track\fP +\fB\-\-no\-track\fR .RS 4 -By default, Cargo keeps track of the installed packages with a metadata -file stored in the installation root directory. This flag tells Cargo not -to use or create that file. With this flag, Cargo will refuse to overwrite -any existing files unless the \fB\-\-force\fP flag is used. This also disables -Cargo\(cqs ability to protect against multiple concurrent invocations of -Cargo installing at the same time. +By default, Cargo keeps track of the installed packages with a metadata file +stored in the installation root directory. This flag tells Cargo not to use or +create that file. With this flag, Cargo will refuse to overwrite any existing +files unless the \fB\-\-force\fR flag is used. This also disables Cargo's ability to +protect against multiple concurrent invocations of Cargo installing at the +same time. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Install only the specified binary. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Install all binaries. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Install only the specified example. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Install all examples. .RE .sp -\fB\-\-root\fP \fIDIR\fP +\fB\-\-root\fR \fIdir\fR .RS 4 Directory to install packages into. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Install for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .sp -\fB\-\-debug\fP +\fB\-\-debug\fR .RS 4 -Build with the \fBdev\fP profile instead the \fBrelease\fP profile. +Build with the \fBdev\fR profile instead the \fBrelease\fR profile. .RE .SS "Manifest Options" .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -383,169 +282,120 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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 or upgrade a package from crates.io: +\h'-04' 1.\h'+01'Install or upgrade a package from crates.io: .sp -.if n .RS 4 +.RS 4 .nf cargo install ripgrep .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Install or reinstall the package in the current directory: +\h'-04' 2.\h'+01'Install or reinstall the package in the current directory: .sp -.if n .RS 4 +.RS 4 .nf cargo install \-\-path . .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -View the list of installed packages: +\h'-04' 3.\h'+01'View the list of installed packages: .sp -.if n .RS 4 +.RS 4 .nf cargo install \-\-list .fi -.if n .RE +.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 +\fBcargo\fR(1), \fBcargo\-uninstall\fR(1), \fBcargo\-search\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-locate-project.1 b/src/etc/man/cargo-locate-project.1 index 4a73aed7c35..29283dde5ac 100644 --- a/src/etc/man/cargo-locate-project.1 +++ b/src/etc/man/cargo-locate-project.1 @@ -1,165 +1,106 @@ '\" t -.\" Title: cargo-locate-project -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-LOCATE\-PROJECT" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-LOCATE\-PROJECT" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" -cargo\-locate\-project \- Print a JSON representation of a Cargo.toml file\(aqs location +cargo\-locate\-project \- Print a JSON representation of a Cargo.toml file's location .SH "SYNOPSIS" -.sp -\fBcargo locate\-project [\fIOPTIONS\fP]\fP +\fBcargo locate\-project\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp This command will print a JSON object to stdout with the full path to the -\fBCargo.toml\fP manifest. +\fBCargo.toml\fR manifest. .sp -See also \fBcargo\-metadata\fP(1) which is capable of returning the path to a +See also \fBcargo\-metadata\fR(1) which is capable of returning the path to a workspace root. .SH "OPTIONS" .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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 +\h'-04' 1.\h'+01'Display the path to the manifest based on the current directory: +.sp +.RS 4 .nf cargo locate\-project .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-login.1 b/src/etc/man/cargo-login.1 index 1ac847fb566..87129c1f5ff 100644 --- a/src/etc/man/cargo-login.1 +++ b/src/etc/man/cargo-login.1 @@ -1,173 +1,113 @@ '\" t -.\" Title: cargo-login -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-LOGIN" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-LOGIN" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-login \- Save an API token from the registry locally .SH "SYNOPSIS" -.sp -\fBcargo login [\fIOPTIONS\fP] [\fITOKEN\fP]\fP +\fBcargo login\fR [\fIoptions\fR] [\fItoken\fR] .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.toml\fP. \fBCARGO_HOME\fP -defaults to \fB.cargo\fP in your home directory. +authentication, such as \fBcargo\-publish\fR(1), will be automatically +authenticated. The token is saved in \fB$CARGO_HOME/credentials.toml\fR\&. \fBCARGO_HOME\fR +defaults to \fB\&.cargo\fR in your home directory. .sp -If the \fITOKEN\fP argument is not specified, it will be read from stdin. +If the \fItoken\fR argument is not specified, it will be read from stdin. .sp -The API token for crates.io may be retrieved from \c -.URL "https://crates.io/me" "" "." +The API token for crates.io may be retrieved from \&. .sp Take care to keep the token secret, it should not be shared with anyone else. .SH "OPTIONS" .SS "Login Options" .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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 +\h'-04' 1.\h'+01'Save the API token to disk: +.sp +.RS 4 .nf cargo login .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-metadata.1 b/src/etc/man/cargo-metadata.1 index 21cee8dfd92..3c0770ab5cc 100644 --- a/src/etc/man/cargo-metadata.1 +++ b/src/etc/man/cargo-metadata.1 @@ -1,53 +1,27 @@ '\" t -.\" Title: cargo-metadata -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-07-04 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-METADATA" "1" "2020-07-04" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-METADATA" "1" .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 < > -.\} +.ss \n[.ss] 0 +.sp +:source\-highlighter: highlightjs .SH "NAME" cargo\-metadata \- Machine\-readable metadata about the current package .SH "SYNOPSIS" -.sp -\fBcargo metadata [\fIOPTIONS\fP]\fP +\fBcargo metadata\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Output JSON to stdout containing information about the workspace members and resolved dependencies of the current package. .sp -It is recommended to include the \fB\-\-format\-version\fP flag to future\-proof +It is recommended to include the \fB\-\-format\-version\fR flag to future\-proof your code to ensure the output is in the format you are expecting. .sp -See the \c -.URL "https://crates.io/crates/cargo_metadata" "cargo_metadata crate" +See the \fIcargo_metadata crate\fR for a Rust API for reading the metadata. .SH "OUTPUT FORMAT" -.sp The output has the following format: .sp -.if n .RS 4 +.RS 4 .nf { /* Array of all packages in the workspace. @@ -77,7 +51,7 @@ The output has the following format: Example: "git+https://github.com/rust\-lang/cargo?rev=5e85ba14aaa20f8133863373404cb0af69eeef2c#5e85ba14aaa20f8133863373404cb0af69eeef2c" */ "source": null, - /* Array of dependencies declared in the package\(aqs manifest. */ + /* Array of dependencies declared in the package's manifest. */ "dependencies": [ { /* The name of the dependency. */ @@ -156,8 +130,7 @@ The output has the following format: the target is compatible with doc testing. */ "doctest": false, - /* Whether or not this target has the `test` field set in the manifest, - causing it to be compiled with `--test`. + /* Whether or not this target should be built and run with `\-\-test` */ "test": true } @@ -173,7 +146,7 @@ The output has the following format: "feat1": [], "feat2": [] }, - /* Absolute path to this package\(aqs manifest. */ + /* 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. @@ -251,7 +224,7 @@ The output has the following format: */ "deps": [ { - /* The name of the dependency\(aqs library target. + /* The name of the dependency's library target. If this is a renamed dependency, this is the new name. */ @@ -304,137 +277,117 @@ The output has the following format: } } .fi -.if n .RE +.RE .SH "OPTIONS" .SS "Output Options" .sp -\fB\-\-no\-deps\fP +\fB\-\-no\-deps\fR .RS 4 -Output information only about the workspace members and don\(cqt fetch +Output information only about the workspace members and don't fetch dependencies. .RE .sp -\fB\-\-format\-version\fP \fIVERSION\fP +\fB\-\-format\-version\fR \fIversion\fR .RS 4 -Specify the version of the output format to use. Currently \fB1\fP is the only +Specify the version of the output format to use. Currently \fB1\fR is the only possible value. .RE .sp -\fB\-\-filter\-platform\fP \fITRIPLE\fP +\fB\-\-filter\-platform\fR \fItriple\fR .RS 4 -This filters the \fBresolve\fP output to only include dependencies for the +This filters the \fBresolve\fR output to only include dependencies for the given target triple. Without this flag, the resolve includes all targets. .sp Note that the dependencies listed in the "packages" array still includes all dependencies. Each package definition is intended to be an unaltered -reproduction of the information within \fBCargo.toml\fP. +reproduction of the information within \fBCargo.toml\fR\&. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -444,69 +397,54 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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 +\h'-04' 1.\h'+01'Output JSON about the current package: +.sp +.RS 4 .nf cargo metadata \-\-format\-version=1 .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-new.1 b/src/etc/man/cargo-new.1 index 68eb8750d6f..02eeb6aeb8c 100644 --- a/src/etc/man/cargo-new.1 +++ b/src/etc/man/cargo-new.1 @@ -1,369 +1,209 @@ '\" t -.\" Title: cargo-new -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-NEW" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-NEW" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-new \- Create a new Cargo package .SH "SYNOPSIS" -.sp -\fBcargo new [\fIOPTIONS\fP] \fIPATH\fP\fP +\fBcargo new\fR [\fIoptions\fR] \fIpath\fR .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, +includes a simple template with a \fBCargo.toml\fR manifest, sample source file, and a VCS ignore file. If the directory is not already in a VCS repository, -then a new repository is created (see \fB\-\-vcs\fP below). +then a new repository is created (see \fB\-\-vcs\fR 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 +\h'-04'\(bu\h'+02'\fBcargo\-new.name\fR 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 +\h'-04'\(bu\h'+02'\fBCARGO_NAME\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_NAME\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_NAME\fR 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 +\h'-04'\(bu\h'+02'\fBuser.name\fR 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 +\h'-04'\(bu\h'+02'\fBUSER\fR 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 +\h'-04'\(bu\h'+02'\fBUSERNAME\fR 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 +\h'-04'\(bu\h'+02'\fBNAME\fR 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 +\h'-04'\(bu\h'+02'\fBcargo\-new.email\fR 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 +\h'-04'\(bu\h'+02'\fBCARGO_EMAIL\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_AUTHOR_EMAIL\fR 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 +\h'-04'\(bu\h'+02'\fBGIT_COMMITTER_EMAIL\fR 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 +\h'-04'\(bu\h'+02'\fBuser.email\fR 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 +\h'-04'\(bu\h'+02'\fBEMAIL\fR environment variable .RE .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" " " -for more information about +See \fIthe reference\fR for more information about configuration files. .sp -See \fBcargo\-init\fP(1) for a similar command which will create a new manifest +See \fBcargo\-init\fR(1) for a similar command which will create a new manifest in an existing directory. .SH "OPTIONS" .SS "New Options" .sp -\fB\-\-bin\fP +\fB\-\-bin\fR .RS 4 -Create a package with a binary target (\fBsrc/main.rs\fP). +Create a package with a binary target (\fBsrc/main.rs\fR). This is the default behavior. .RE .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Create a package with a library target (\fBsrc/lib.rs\fP). +Create a package with a library target (\fBsrc/lib.rs\fR). .RE .sp -\fB\-\-edition\fP \fIEDITION\fP +\fB\-\-edition\fR \fIedition\fR .RS 4 Specify the Rust edition to use. Default is 2018. Possible values: 2015, 2018 .RE .sp -\fB\-\-name\fP \fINAME\fP +\fB\-\-name\fR \fIname\fR .RS 4 Set the package name. Defaults to the directory name. .RE .sp -\fB\-\-vcs\fP \fIVCS\fP +\fB\-\-vcs\fR \fIvcs\fR .RS 4 Initialize a new VCS repository for the given version control system (git, hg, pijul, or fossil) or do not initialize any version control at all -(none). If not specified, defaults to \fBgit\fP or the configuration value -\fBcargo\-new.vcs\fP, or \fBnone\fP if already inside a VCS repository. +(none). If not specified, defaults to \fBgit\fR or the configuration value +\fBcargo\-new.vcs\fR, or \fBnone\fR if already inside a VCS repository. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -This sets the \fBpublish\fP field in \fBCargo.toml\fP to the given registry name +This sets the \fBpublish\fR field in \fBCargo.toml\fR to the given registry name which will restrict publishing only to that registry. .sp -Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry defined by the \fBregistry.default\fP -config key is used. If the default registry is not set and \fB\-\-registry\fP is not -used, the \fBpublish\fP field will not be set which means that publishing will not +Registry names are defined in \fICargo config files\fR \&. +If not specified, the default registry defined by the \fBregistry.default\fR +config key is used. If the default registry is not set and \fB\-\-registry\fR is not +used, the \fBpublish\fR field will not be set which means that publishing will not be restricted. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Create a binary Cargo package in the given directory: .sp -.if n .RS 4 +.RS 4 .nf cargo new foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-init\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-init\fR(1) diff --git a/src/etc/man/cargo-owner.1 b/src/etc/man/cargo-owner.1 index 8df4f1d8c3a..81a25f522a2 100644 --- a/src/etc/man/cargo-owner.1 +++ b/src/etc/man/cargo-owner.1 @@ -1,248 +1,175 @@ '\" t -.\" Title: cargo-owner -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-OWNER" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-OWNER" "1" .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 < > -.\} +.ss \n[.ss] 0 .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 +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-add\fR \fIlogin\fR [\fIcrate\fR] .br -\fBcargo owner [\fIOPTIONS\fP] \-\-remove \fILOGIN\fP [\fICRATE\fP]\fP +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-remove\fR \fIlogin\fR [\fIcrate\fR] .br -\fBcargo owner [\fIOPTIONS\fP] \-\-list [\fICRATE\fP]\fP +\fBcargo owner\fR [\fIoptions\fR] \fB\-\-list\fR [\fIcrate\fR] .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). +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). .sp If the crate name is not specified, it will use the package name from the current directory. .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html#cargo\-owner" "the reference" " " -for more +See \fIthe reference\fR for more information about owners and publishing. .SH "OPTIONS" .SS "Owner Options" .sp -\fB\-a\fP, \fB\-\-add\fP \fILOGIN\fP... +\fB\-a\fR, +\fB\-\-add\fR \fIlogin\fR\&... .RS 4 Invite the given user or team as an owner. .RE .sp -\fB\-r\fP, \fB\-\-remove\fP \fILOGIN\fP... +\fB\-r\fR, +\fB\-\-remove\fR \fIlogin\fR\&... .RS 4 Remove the given user or team as an owner. .RE .sp -\fB\-l\fP, \fB\-\-list\fP +\fB\-l\fR, +\fB\-\-list\fR .RS 4 List owners of a crate. .RE .sp -\fB\-\-token\fP \fITOKEN\fP +\fB\-\-token\fR \fItoken\fR .RS 4 API token to use when authenticating. This overrides the token stored in -the credentials file (which is created by \fBcargo\-login\fP(1)). +the credentials file (which is created by \fBcargo\-login\fR(1)). .sp -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " " -environment variables can be +\fICargo config\fR environment variables can be used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment +crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment variable. Tokens for other registries may be specified with environment -variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name of the registry in all capital letters. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'List owners of a package: .sp -.if n .RS 4 +.RS 4 .nf cargo owner \-\-list foo .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Invite an owner to a package: +\h'-04' 2.\h'+01'Invite an owner to a package: .sp -.if n .RS 4 +.RS 4 .nf cargo owner \-\-add username foo .fi -.if n .RE +.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: +\h'-04' 3.\h'+01'Remove an owner from a package: .sp -.if n .RS 4 +.RS 4 .nf cargo owner \-\-remove username foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-login\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-package.1 b/src/etc/man/cargo-package.1 index 0a80a18203e..f8c10de6d2c 100644 --- a/src/etc/man/cargo-package.1 +++ b/src/etc/man/cargo-package.1 @@ -1,270 +1,169 @@ '\" t -.\" Title: cargo-package -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-PACKAGE" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-PACKAGE" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-package \- Assemble the local package into a distributable tarball .SH "SYNOPSIS" -.sp -\fBcargo package [\fIOPTIONS\fP]\fP +\fBcargo package\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This command will create a distributable, compressed \fB.crate\fP file with the +This command will create a distributable, compressed \fB\&.crate\fR file with the source code of the package in the current directory. The resulting file will -be stored in the \fBtarget/package\fP directory. This performs the following +be stored in the \fBtarget/package\fR 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 +\h'-04' 1.\h'+01'Load and check the current workspace, performing some basic checks. +.sp +.RS 4 +\h'-04'\(bu\h'+02'Path dependencies are not allowed unless they have a version key. Cargo will ignore the path key for dependencies in published packages. -\fBdev\-dependencies\fP do not have this restriction. +\fBdev\-dependencies\fR do not have this restriction. .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. +\h'-04' 2.\h'+01'Create the compressed \fB\&.crate\fR 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. +\h'-04'\(bu\h'+02'The original \fBCargo.toml\fR file is rewritten and normalized. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB[patch]\fP, \fB[replace]\fP, and \fB[workspace]\fP sections are removed from the +\h'-04'\(bu\h'+02'\fB[patch]\fR, \fB[replace]\fR, and \fB[workspace]\fR sections are removed from the manifest. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCargo.lock\fP is automatically included if the package contains an -executable binary or example target. \fBcargo\-install\fP(1) will use the -packaged lock file if the \fB\-\-locked\fP flag is used. +\h'-04'\(bu\h'+02'\fBCargo.lock\fR is automatically included if the package contains an +executable binary or example target. \fBcargo\-install\fR(1) will use the +packaged lock file if the \fB\-\-locked\fR flag is used. .RE .sp .RS 4 -.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 +\h'-04'\(bu\h'+02'A \fB\&.cargo_vcs_info.json\fR file is included that contains information about the current VCS checkout hash if available (not included with -\fB\-\-allow\-dirty\fP). +\fB\-\-allow\-dirty\fR). .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. +\h'-04' 3.\h'+01'Extract the \fB\&.crate\fR file and build it to verify it can build. .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -This will rebuild your package from scratch to ensure that it can be -built from a pristine state. The \fB\-\-no\-verify\fP flag can be used to skip +\h'-04'\(bu\h'+02'This will rebuild your package from scratch to ensure that it can be +built from a pristine state. The \fB\-\-no\-verify\fR flag can be used to skip this step. .RE .RE .sp .RS 4 -.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. +\h'-04' 4.\h'+01'Check that build scripts did not modify any source files. .RE .sp -The list of files included can be controlled with the \fBinclude\fP and \fBexclude\fP +The list of files included can be controlled with the \fBinclude\fR and \fBexclude\fR fields in the manifest. .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html" "the reference" " " -for more details about +See \fIthe reference\fR for more details about packaging and publishing. .SH "OPTIONS" .SS "Package Options" .sp -\fB\-l\fP, \fB\-\-list\fP +\fB\-l\fR, +\fB\-\-list\fR .RS 4 Print files included in a package without making one. .RE .sp -\fB\-\-no\-verify\fP +\fB\-\-no\-verify\fR .RS 4 -Don\(cqt verify the contents by building them. +Don't verify the contents by building them. .RE .sp -\fB\-\-no\-metadata\fP +\fB\-\-no\-metadata\fR .RS 4 -Ignore warnings about a lack of human\-usable metadata (such as the -description or the license). +Ignore warnings about a lack of human\-usable metadata (such as the description +or the license). .RE .sp -\fB\-\-allow\-dirty\fP +\fB\-\-allow\-dirty\fR .RS 4 Allow working directories with uncommitted VCS changes to be packaged. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Package for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -274,135 +173,100 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Create a compressed \fB\&.crate\fR file of the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo package .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-pkgid.1 b/src/etc/man/cargo-pkgid.1 index 80b5fbbe15d..128587ec44b 100644 --- a/src/etc/man/cargo-pkgid.1 +++ b/src/etc/man/cargo-pkgid.1 @@ -1,43 +1,17 @@ '\" t -.\" Title: cargo-pkgid -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-PKGID" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-PKGID" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-pkgid \- Print a fully qualified package specification .SH "SYNOPSIS" -.sp -\fBcargo pkgid [\fIOPTIONS\fP] [\fISPEC\fP]\fP +\fBcargo pkgid\fR [\fIoptions\fR] [\fIspec\fR] .SH "DESCRIPTION" -.sp -Given a \fISPEC\fP argument, print out the fully qualified package ID specifier +Given a \fIspec\fR argument, print out the fully qualified package ID specifier for a package or dependency in the current workspace. This command will -generate an error if \fISPEC\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 +generate an error if \fIspec\fR is ambiguous as to which package it refers to in +the dependency graph. If no \fIspec\fR is given, then the specifier for the local package is printed. .sp This command requires that a lockfile is available and dependencies have been @@ -45,156 +19,116 @@ 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 +long as it matches only one package. The format of a \fIspec\fR 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 +\fIname\fR T}:T{ -.sp -\fBbitflags\fP +\fBbitflags\fR T} T{ -.sp -\fINAME\fP\fB:\fP\fIVERSION\fP +\fIname\fR\fB:\fR\fIversion\fR T}:T{ -.sp -\fBbitflags:1.0.4\fP +\fBbitflags:1.0.4\fR T} T{ -.sp -\fIURL\fP +\fIurl\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/cargo" "" "\fP" +\fBhttps://github.com/rust\-lang/cargo\fR T} T{ -.sp -\fIURL\fP\fB#\fP\fIVERSION\fP +\fIurl\fR\fB#\fR\fIversion\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/cargo#0.33.0" "" "\fP" +\fBhttps://github.com/rust\-lang/cargo#0.33.0\fR T} T{ -.sp -\fIURL\fP\fB#\fP\fINAME\fP +\fIurl\fR\fB#\fR\fIname\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/crates.io\-index#bitflags" "" "\fP" +\fBhttps://github.com/rust\-lang/crates.io\-index#bitflags\fR T} T{ -.sp -\fIURL\fP\fB#\fP\fINAME\fP\fB:\fP\fIVERSION\fP +\fIurl\fR\fB#\fR\fIname\fR\fB:\fR\fIversion\fR T}:T{ -.sp -\fB\c -.URL "https://github.com/rust\-lang/cargo#crates\-io:0.21.0" "" "\fP" +\fBhttps://github.com/rust\-lang/cargo#crates\-io:0.21.0\fR T} .TE .sp .SH "OPTIONS" .SS "Package Selection" .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 Get the package ID for the given package instead of the current package. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -204,103 +138,74 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Retrieve package specification for \fBfoo\fR package: .sp -.if n .RS 4 +.RS 4 .nf cargo pkgid foo .fi -.if n .RE +.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: +\h'-04' 2.\h'+01'Retrieve package specification for version 1.0.0 of \fBfoo\fR: .sp -.if n .RS 4 +.RS 4 .nf cargo pkgid foo:1.0.0 .fi -.if n .RE +.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: +\h'-04' 3.\h'+01'Retrieve package specification for \fBfoo\fR from crates.io: .sp -.if n .RS 4 +.RS 4 .nf cargo pkgid https://github.com/rust\-lang/crates.io\-index#foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-generate\-lockfile\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-publish.1 b/src/etc/man/cargo-publish.1 index 716127628cb..1bac92f5ef2 100644 --- a/src/etc/man/cargo-publish.1 +++ b/src/etc/man/cargo-publish.1 @@ -1,220 +1,157 @@ '\" t -.\" Title: cargo-publish -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-PUBLISH" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-PUBLISH" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-publish \- Upload a package to the registry .SH "SYNOPSIS" -.sp -\fBcargo publish [\fIOPTIONS\fP]\fP +\fBcargo publish\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp -This command will create a distributable, compressed \fB.crate\fP file with the +This command will create a distributable, compressed \fB\&.crate\fR file with the source code of the package in the current directory and upload it to a -registry. The default registry is \c -.URL "https://crates.io" "" "." -This performs the +registry. The default registry is \&. 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: +\h'-04' 1.\h'+01'Performs a few checks, including: .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. +\h'-04'\(bu\h'+02'Checks the \fBpackage.publish\fR key in the manifest for restrictions on +which registries you are allowed to publish to. .RE .RE .sp .RS 4 -.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). +\h'-04' 2.\h'+01'Create a \fB\&.crate\fR file by following the steps in \fBcargo\-package\fR(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 +\h'-04' 3.\h'+01'Upload the crate to the registry. Note that the server will perform additional checks on the crate. .RE .sp -This command requires you to be authenticated with either the \fB\-\-token\fP option -or using \fBcargo\-login\fP(1). +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). .sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/publishing.html" "the reference" " " -for more details about +See \fIthe reference\fR for more details about packaging and publishing. .SH "OPTIONS" .SS "Publish Options" .sp -\fB\-\-dry\-run\fP +\fB\-\-dry\-run\fR .RS 4 Perform all checks without uploading. .RE .sp -\fB\-\-token\fP \fITOKEN\fP +\fB\-\-token\fR \fItoken\fR .RS 4 API token to use when authenticating. This overrides the token stored in -the credentials file (which is created by \fBcargo\-login\fP(1)). +the credentials file (which is created by \fBcargo\-login\fR(1)). .sp -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " " -environment variables can be +\fICargo config\fR environment variables can be used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment +crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment variable. Tokens for other registries may be specified with environment -variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name of the registry in all capital letters. .RE .sp -\fB\-\-no\-verify\fP +\fB\-\-no\-verify\fR .RS 4 -Don\(cqt verify the contents by building them. +Don't verify the contents by building them. .RE .sp -\fB\-\-allow\-dirty\fP +\fB\-\-allow\-dirty\fR .RS 4 Allow working directories with uncommitted VCS changes to be packaged. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Publish for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -224,135 +161,100 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. Defaults to the number of CPUs. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Publish the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo publish .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-package\fP(1), \fBcargo\-login\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-package\fR(1), \fBcargo\-login\fR(1) diff --git a/src/etc/man/cargo-run.1 b/src/etc/man/cargo-run.1 index 16c1da54a04..4ba8a36bda6 100644 --- a/src/etc/man/cargo-run.1 +++ b/src/etc/man/cargo-run.1 @@ -1,292 +1,200 @@ '\" t -.\" Title: cargo-run -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-04-21 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-RUN" "1" "2020-04-21" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-RUN" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-run \- Run the current package .SH "SYNOPSIS" -.sp -\fBcargo run [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +\fBcargo run\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] .SH "DESCRIPTION" -.sp Run a binary or example of the local package. .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. +All the arguments following the two dashes (\fB\-\-\fR) are passed to the binary to +run. If you're passing arguments to both Cargo and the binary, the ones after +\fB\-\-\fR go to the binary, the ones before go to Cargo. .SH "OPTIONS" .SS "Package Selection" -.sp -By default, the package in the current working directory is selected. The \fB\-p\fP +By default, the package in the current working directory is selected. The \fB\-p\fR flag can be used to choose a different package in a workspace. .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 -The package to run. See \fBcargo\-pkgid\fP(1) for -the SPEC format. +The package to run. See \fBcargo\-pkgid\fR(1) for the SPEC +format. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo run\fP will run the binary +When no target selection options are given, \fBcargo run\fR will run the binary target. If there are multiple binary targets, you must pass a target flag to -choose one. Or, the \fBdefault\-run\fP field may be specified in the \fB[package]\fP -section of \fBCargo.toml\fP to choose the name of the binary to run by default. +choose one. Or, the \fBdefault\-run\fR field may be specified in the \fB[package]\fR +section of \fBCargo.toml\fR to choose the name of the binary to run by default. .sp -\fB\-\-bin\fP \fINAME\fP +\fB\-\-bin\fR \fIname\fR .RS 4 Run the specified binary. .RE .sp -\fB\-\-example\fP \fINAME\fP +\fB\-\-example\fR \fIname\fR .RS 4 Run the specified example. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Run for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Run optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Run optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -296,146 +204,110 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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 (assuming only one binary): +\h'-04' 1.\h'+01'Build the local package and run its main target (assuming only one binary): .sp -.if n .RS 4 +.RS 4 .nf cargo run .fi -.if n .RE +.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: +\h'-04' 2.\h'+01'Run an example with extra arguments: .sp -.if n .RS 4 +.RS 4 .nf cargo run \-\-example exname \-\- \-\-exoption exarg1 exarg2 .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1) diff --git a/src/etc/man/cargo-rustc.1 b/src/etc/man/cargo-rustc.1 index a8b6f14eaeb..6d42059db58 100644 --- a/src/etc/man/cargo-rustc.1 +++ b/src/etc/man/cargo-rustc.1 @@ -1,363 +1,267 @@ '\" t -.\" Title: cargo-rustc -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-RUSTC" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-RUSTC" "1" .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 < > -.\} +.ss \n[.ss] 0 .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 +\fBcargo rustc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] .SH "DESCRIPTION" -.sp -The specified target for the current package (or package specified by \fB\-p\fP if +The specified target for the current package (or package specified by \fB\-p\fR if provided) will be compiled along with all of its dependencies. The specified -\fIARGS\fP will all be passed to the final compiler invocation, not any of the +\fIargs\fR will all be passed to the final compiler invocation, not any of the dependencies. Note that the compiler will still unconditionally receive -arguments such as \fB\-L\fP, \fB\-\-extern\fP, and \fB\-\-crate\-type\fP, and the specified -\fIARGS\fP will simply be added to the compiler invocation. +arguments such as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified +\fIargs\fR will simply be added to the compiler invocation. .sp -See \c -.URL "https://doc.rust\-lang.org/rustc/index.html" "" " " -for documentation on rustc +See 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 +package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which target is compiled. -To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fP -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable" " " -or the -\fBbuild.rustflags\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +.sp +To pass flags to all compiler processes spawned by Cargo, use the \fBRUSTFLAGS\fR +\fIenvironment variable\fR or the +\fBbuild.rustflags\fR \fIconfig value\fR \&. .SH "OPTIONS" .SS "Package Selection" -.sp -By default, the package in the current working directory is selected. The \fB\-p\fP +By default, the package in the current working directory is selected. The \fB\-p\fR flag can be used to choose a different package in a workspace. .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 -The package to build. See \fBcargo\-pkgid\fP(1) for -the SPEC format. +The package to build. See \fBcargo\-pkgid\fR(1) for the SPEC +format. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo rustc\fP will build all +When no target selection options are given, \fBcargo rustc\fR will build all binary and library targets of the selected package. .sp -Passing target selection flags will build only the -specified targets. +Passing target selection flags will build only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Build the package\(cqs library. +Build the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Build the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Build all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Build the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Build all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Build the specified integration test. This flag may be specified multiple -times. +Build the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Build all targets in test mode that have the \fBtest = true\fP manifest +Build all targets in test mode that have the \fBtest = true\fR manifest flag set. By default this includes the library and binaries built as unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Build the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Build all targets in benchmark mode that have the \fBbench = true\fP +Build all targets in benchmark mode that have the \fBbench = true\fR manifest flag set. By default this includes the library and binaries built as benchmarks, and bench targets. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Build all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Build for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Build optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Build optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -367,147 +271,111 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Check if your package (not including dependencies) uses unsafe code: .sp -.if n .RS 4 +.RS 4 .nf cargo rustc \-\-lib \-\- \-D unsafe\-code .fi -.if n .RE +.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 +\h'-04' 2.\h'+01'Try an experimental flag on the nightly compiler, such as this which prints the size of every type: .sp -.if n .RS 4 +.RS 4 .nf cargo rustc \-\-lib \-\- \-Z print\-type\-sizes .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-build\fP(1), \fBrustc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-build\fR(1), \fBrustc\fR(1) diff --git a/src/etc/man/cargo-rustdoc.1 b/src/etc/man/cargo-rustdoc.1 index 88271e1462a..86432194129 100644 --- a/src/etc/man/cargo-rustdoc.1 +++ b/src/etc/man/cargo-rustdoc.1 @@ -1,373 +1,276 @@ '\" t -.\" Title: cargo-rustdoc -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-RUSTDOC" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-RUSTDOC" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" -cargo\-rustdoc \- Build a package\(aqs documentation, using specified custom flags +cargo\-rustdoc \- Build a package's documentation, using specified custom flags .SH "SYNOPSIS" -.sp -\fBcargo rustdoc [\fIOPTIONS\fP] [\-\- \fIARGS\fP]\fP +\fBcargo rustdoc\fR [\fIoptions\fR] [\fB\-\-\fR \fIargs\fR] .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 +The specified target for the current package (or package specified by \fB\-p\fR if +provided) will be documented with the specified \fIargs\fR being passed to the final rustdoc invocation. Dependencies will not be documented as part of this command. Note that rustdoc will still unconditionally receive arguments such -as \fB\-L\fP, \fB\-\-extern\fP, and \fB\-\-crate\-type\fP, and the specified \fIARGS\fP will simply +as \fB\-L\fR, \fB\-\-extern\fR, and \fB\-\-crate\-type\fR, and the specified \fIargs\fR will simply be added to the rustdoc invocation. .sp -See \c -.URL "https://doc.rust\-lang.org/rustdoc/index.html" "" " " -for documentation on rustdoc +See 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 +package the filters of \fB\-\-lib\fR, \fB\-\-bin\fR, etc, must be used to select which target is compiled. +.sp To pass flags to all rustdoc processes spawned by Cargo, use the -\fBRUSTDOCFLAGS\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "environment variable" -or the \fBbuild.rustdocflags\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +\fBRUSTDOCFLAGS\fR \fIenvironment variable\fR +or the \fBbuild.rustdocflags\fR \fIconfig value\fR \&. .SH "OPTIONS" .SS "Documentation Options" .sp -\fB\-\-open\fP +\fB\-\-open\fR .RS 4 Open the docs in a browser after building them. This will use your default -browser unless you define another one in the \fBBROWSER\fP environment -variable. +browser unless you define another one in the \fBBROWSER\fR environment variable. .RE .SS "Package Selection" -.sp -By default, the package in the current working directory is selected. The \fB\-p\fP +By default, the package in the current working directory is selected. The \fB\-p\fR flag can be used to choose a different package in a workspace. .sp -\fB\-p\fP \fISPEC\fP, \fB\-\-package\fP \fISPEC\fP +\fB\-p\fR \fIspec\fR, +\fB\-\-package\fR \fIspec\fR .RS 4 -The package to document. See \fBcargo\-pkgid\fP(1) for -the SPEC format. +The package to document. See \fBcargo\-pkgid\fR(1) for the SPEC +format. .RE .SS "Target Selection" -.sp -When no target selection options are given, \fBcargo rustdoc\fP will document all +When no target selection options are given, \fBcargo rustdoc\fR will document all binary and library targets of the selected package. The binary will be skipped if its name is the same as the lib target. Binaries are skipped if they have -\fBrequired\-features\fP that are missing. +\fBrequired\-features\fR that are missing. .sp -Passing target selection flags will document only the -specified targets. +Passing target selection flags will document only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Document the package\(cqs library. +Document the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Document the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Document all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Document the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Document all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Document the specified integration test. This flag may be specified multiple -times. +Document the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Document all targets in test mode that have the \fBtest = true\fP manifest +Document all targets in test mode that have the \fBtest = true\fR manifest flag set. By default this includes the library and binaries built as unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Document the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Document all targets in benchmark mode that have the \fBbench = true\fP +Document all targets in benchmark mode that have the \fBbench = true\fR manifest flag set. By default this includes the library and binaries built as benchmarks, and bench targets. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Document all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Document all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Document for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Document optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Document optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR in the root of the workspace. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -377,129 +280,100 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR profiles. .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Build documentation with custom CSS included from a given file: .sp -.if n .RS 4 +.RS 4 .nf cargo rustdoc \-\-lib \-\- \-\-extend\-css extra.css .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-doc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-doc\fR(1), \fBrustdoc\fR(1) diff --git a/src/etc/man/cargo-search.1 b/src/etc/man/cargo-search.1 index 3999d4b0ff0..350b2dbb8aa 100644 --- a/src/etc/man/cargo-search.1 +++ b/src/etc/man/cargo-search.1 @@ -1,177 +1,116 @@ '\" t -.\" Title: cargo-search -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-SEARCH" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-SEARCH" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-search \- Search packages in crates.io .SH "SYNOPSIS" -.sp -\fBcargo search [\fIOPTIONS\fP] [\fIQUERY\fP...]\fP +\fBcargo search\fR [\fIoptions\fR] [\fIquery\fR\&...] .SH "DESCRIPTION" -.sp -This performs a textual search for crates on \c -.URL "https://crates.io" "" "." -The matching +This performs a textual search for crates on \&. The matching crates will be displayed along with their description in TOML format suitable -for copying into a \fBCargo.toml\fP manifest. +for copying into a \fBCargo.toml\fR manifest. .SH "OPTIONS" .SS "Search Options" .sp -\fB\-\-limit\fP \fILIMIT\fP +\fB\-\-limit\fR \fIlimit\fR .RS 4 Limit the number of results (default: 10, max: 100). .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Search for a package from crates.io: .sp -.if n .RS 4 +.RS 4 .nf cargo search serde .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-install\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-install\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo-test.1 b/src/etc/man/cargo-test.1 index bbcc99186ca..c21747ee4c7 100644 --- a/src/etc/man/cargo-test.1 +++ b/src/etc/man/cargo-test.1 @@ -1,526 +1,380 @@ '\" t -.\" Title: cargo-test -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-07-28 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-TEST" "1" "2020-07-28" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-TEST" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-test \- Execute unit and integration tests of a package .SH "SYNOPSIS" -.sp -\fBcargo test [\fIOPTIONS\fP] [TESTNAME] [\-\- \fITEST\-OPTIONS\fP]\fP +\fBcargo test\fR [\fIoptions\fR] [\fItestname\fR] [\fB\-\-\fR \fItest\-options\fR] .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 \-\- \-\-help\fP. +The test filtering argument \fBTESTNAME\fR and all the arguments following the two +dashes (\fB\-\-\fR) are passed to the test binaries and thus to \fIlibtest\fR (rustc's +built in unit\-test and micro\-benchmarking framework). If you're passing +arguments to both Cargo and the binary, the ones after \fB\-\-\fR go to the binary, +the ones before go to Cargo. For details about libtest's arguments see the +output of \fBcargo test \-\- \-\-help\fR\&. .sp -As an example, this will filter for tests with \fBfoo\fP in their name and run them +As an example, this will filter for tests with \fBfoo\fR in their name and run them on 3 threads in parallel: .sp -.if n .RS 4 +.RS 4 .nf cargo test foo \-\- \-\-test\-threads 3 .fi -.if n .RE +.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. \fB#[bench]\fP +Tests are built with the \fB\-\-test\fR option to \fBrustc\fR which creates an +executable with a \fBmain\fR function that automatically runs all functions +annotated with the \fB#[test]\fR attribute in multiple threads. \fB#[bench]\fR annotated functions will also be run with one iteration to verify that they are functional. .sp -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 +The libtest harness may be disabled by setting \fBharness = false\fR in the target +manifest settings, in which case your code will need to provide its own \fBmain\fR function to handle running tests. .sp -Documentation tests are also run by default, which is handled by \fBrustdoc\fP. It +Documentation tests are also run by default, which is handled by \fBrustdoc\fR\&. It extracts code samples from documentation comments and executes them. See the -.URL "https://doc.rust\-lang.org/rustdoc/" "rustdoc book" " " -for more information on +\fIrustdoc book\fR for more information on writing doc tests. .SH "OPTIONS" .SS "Test Options" .sp -\fB\-\-no\-run\fP +\fB\-\-no\-run\fR .RS 4 -Compile, but don\(cqt run tests. +Compile, but don't run tests. .RE .sp -\fB\-\-no\-fail\-fast\fP +\fB\-\-no\-fail\-fast\fR .RS 4 Run all tests regardless of failure. Without this flag, Cargo will exit -after the first executable fails. The Rust test harness will run all -tests within the executable to completion, this flag only applies to -the executable as a whole. +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 selected manifest file (based on the current working directory if -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Test only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Test only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Test all members in the workspace. .RE .sp -\fB\-\-all\fP +\fB\-\-all\fR .RS 4 -Deprecated alias for \fB\-\-workspace\fP. +Deprecated alias for \fB\-\-workspace\fR\&. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR 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 +When no target selection options are given, \fBcargo test\fR 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 +\h'-04'\(bu\h'+02'lib \[em] 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 +\h'-04'\(bu\h'+02'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 +\h'-04'\(bu\h'+02'examples \[em] 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 +\h'-04'\(bu\h'+02'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 +\h'-04'\(bu\h'+02'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 +\h'-04'\(bu\h'+02'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 +\h'-04'\(bu\h'+02'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 +The default behavior can be changed by setting the \fBtest\fR flag for the target +in the manifest settings. Setting examples to \fBtest = true\fR will build and run +the example as a test. Setting targets to \fBtest = false\fR will stop them from being tested by default. Target selection options that take a target by name -ignore the \fBtest\fP flag and will always test the given target. +ignore the \fBtest\fR flag and will always test the given target. .sp -Doc tests for libraries may be disabled by setting \fBdoctest = false\fP for the +Doc tests for libraries may be disabled by setting \fBdoctest = false\fR for the library in the manifest. .sp Binary targets are automatically built if there is an integration test or benchmark. This allows an integration test to execute the binary to exercise -and test its behavior. The \fBCARGO_BIN_EXE_\fP -\c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html#environment\-variables\-cargo\-sets\-for\-crates" "environment variable" +and test its behavior. The \fBCARGO_bin_EXE_\fR +\fIenvironment variable\fR is set when the integration test is built so that it can use the -.URL "https://doc.rust\-lang.org/std/macro.env.html" "\fBenv\fP macro" " " -to locate the +\fI\f(BIenv\fI macro\fR to locate the executable. .sp -Passing target selection flags will test only the -specified targets. +Passing target selection flags will test only the specified +targets. .sp -\fB\-\-lib\fP +\fB\-\-lib\fR .RS 4 -Test the package\(cqs library. +Test the package's library. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 Test the specified binary. This flag may be specified multiple times. .RE .sp -\fB\-\-bins\fP +\fB\-\-bins\fR .RS 4 Test all binary targets. .RE .sp -\fB\-\-example\fP \fINAME\fP... +\fB\-\-example\fR \fIname\fR\&... .RS 4 Test the specified example. This flag may be specified multiple times. .RE .sp -\fB\-\-examples\fP +\fB\-\-examples\fR .RS 4 Test all example targets. .RE .sp -\fB\-\-test\fP \fINAME\fP... +\fB\-\-test\fR \fIname\fR\&... .RS 4 -Test the specified integration test. This flag may be specified multiple -times. +Test the specified integration test. This flag may be specified +multiple times. .RE .sp -\fB\-\-tests\fP +\fB\-\-tests\fR .RS 4 -Test all targets in test mode that have the \fBtest = true\fP manifest +Test all targets in test mode that have the \fBtest = true\fR manifest flag set. By default this includes the library and binaries built as unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). -Targets may be enabled or disabled by setting the \fBtest\fP flag in the +Targets may be enabled or disabled by setting the \fBtest\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-bench\fP \fINAME\fP... +\fB\-\-bench\fR \fIname\fR\&... .RS 4 Test the specified benchmark. This flag may be specified multiple times. .RE .sp -\fB\-\-benches\fP +\fB\-\-benches\fR .RS 4 -Test all targets in benchmark mode that have the \fBbench = true\fP +Test all targets in benchmark mode that have the \fBbench = true\fR manifest flag set. By default this includes the library and binaries built as benchmarks, and bench targets. Be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). -Targets may be enabled or disabled by setting the \fBbench\fP flag in the +Targets may be enabled or disabled by setting the \fBbench\fR flag in the manifest settings for the target. .RE .sp -\fB\-\-all\-targets\fP +\fB\-\-all\-targets\fR .RS 4 -Test all targets. This is equivalent to specifying \fB\-\-lib \-\-bins -\-\-tests \-\-benches \-\-examples\fP. +Test all targets. This is equivalent to specifying \fB\-\-lib \-\-bins \-\-tests \-\-benches \-\-examples\fR\&. .RE .sp -\fB\-\-doc\fP +\fB\-\-doc\fR .RS 4 -Test only the library\(cqs documentation. This cannot be mixed with other +Test only the library's documentation. This cannot be mixed with other target options. .RE .SS "Feature Selection" -.sp The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Compilation Options" .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 Test for the given architecture. The default is the host architecture. The general format of the triple is -\fB\-\-\-\fP. Run \fBrustc \-\-print target\-list\fP for a +\fB\-\-\-\fR\&. Run \fBrustc \-\-print target\-list\fR 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" "." +This may also be specified with the \fBbuild.target\fR +\fIconfig value\fR \&. .sp Note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. See the -.URL "https://doc.rust\-lang.org/cargo/guide/build\-cache.html" "build cache" " " -documentation for more details. +\fIbuild cache\fR documentation for more details. .RE .sp -\fB\-\-release\fP +\fB\-\-release\fR .RS 4 -Test optimized artifacts with the \fBrelease\fP profile. See the -PROFILES section for details on how this affects profile selection. +Test optimized artifacts with the \fBrelease\fR profile. See the +PROFILES section for details on how this affects profile +selection. .RE .SS "Output Options" .sp -\fB\-\-target\-dir\fP \fIDIRECTORY\fP +\fB\-\-target\-dir\fR \fIdirectory\fR .RS 4 Directory for all generated artifacts and intermediate files. May also be -specified with the \fBCARGO_TARGET_DIR\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. +specified with the \fBCARGO_TARGET_DIR\fR environment variable, or the +\fBbuild.target\-dir\fR \fIconfig value\fR \&. Defaults +to \fBtarget\fR 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: +\fB\-\-nocapture\fR to the test binaries: .sp -.if n .RS 4 +.RS 4 .nf cargo test \-\- \-\-nocapture .fi -.if n .RE +.RE .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .sp -\fB\-\-message\-format\fP \fIFMT\fP +\fB\-\-message\-format\fR \fIfmt\fR .RS 4 The output format for diagnostic messages. Can be specified multiple times and consists of comma\-separated values. Valid values: .sp .RS 4 -.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. +\h'-04'\(bu\h'+02'\fBhuman\fR (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 -.\} -\fBshort\fP: Emit shorter, human\-readable text messages. +\h'-04'\(bu\h'+02'\fBshort\fR: Emit shorter, human\-readable text messages. .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. See -\c -.URL "https://doc.rust\-lang.org/cargo/reference/external\-tools.html#json\-messages" "the reference" +\h'-04'\(bu\h'+02'\fBjson\fR: Emit JSON messages to stdout. See +\fIthe reference\fR for more details. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-short\fP: Ensure the \fBrendered\fP field of JSON messages contains +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-short\fR: Ensure the \fBrendered\fR field of JSON messages contains the "short" rendering from rustc. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-diagnostic\-rendered\-ansi\fP: Ensure the \fBrendered\fP field of JSON messages -contains embedded ANSI color codes for respecting rustc\(cqs default color +\h'-04'\(bu\h'+02'\fBjson\-diagnostic\-rendered\-ansi\fR: Ensure the \fBrendered\fR field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color scheme. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBjson\-render\-diagnostics\fP: Instruct Cargo to not include rustc diagnostics in +\h'-04'\(bu\h'+02'\fBjson\-render\-diagnostics\fR: Instruct Cargo to not include rustc diagnostics in in JSON messages printed, but instead Cargo itself should render the -JSON diagnostics coming from rustc. Cargo\(cqs own JSON diagnostics and others +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. .RE .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -530,181 +384,137 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SS "Miscellaneous Options" -.sp -The \fB\-\-jobs\fP argument affects the building of the test executable but does not +The \fB\-\-jobs\fR argument affects the building of the test executable but does not affect how many threads are used when running the tests. The Rust test harness includes an option to control the number of threads used: .sp -.if n .RS 4 +.RS 4 .nf cargo test \-j 2 \-\- \-\-test\-threads=2 .fi -.if n .RE +.RE .sp -\fB\-j\fP \fIN\fP, \fB\-\-jobs\fP \fIN\fP +\fB\-j\fR \fIN\fR, +\fB\-\-jobs\fR \fIN\fR .RS 4 Number of parallel jobs to run. May also be specified with the -\fBbuild.jobs\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." -Defaults to +\fBbuild.jobs\fR \fIconfig value\fR \&. 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/profiles.html" "the reference" -for more details. +and debug settings. See \fIthe reference\fR 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. +\fBdev\fR or \fBtest\fR profiles are used. If the \fB\-\-release\fR flag is given, then the +\fBrelease\fR or \fBbench\fR profiles are used. + .TS allbox tab(:); lt lt lt. T{ -.sp Target T}:T{ -.sp Default Profile T}:T{ -.sp -\fB\-\-release\fP Profile +\fB\-\-release\fR Profile T} T{ -.sp lib, bin, example T}:T{ -.sp -\fBdev\fP +\fBdev\fR T}:T{ -.sp -\fBrelease\fP +\fBrelease\fR T} T{ -.sp -test, bench, or any target -.br -in "test" or "bench" mode +test, bench, or any target in "test" or "bench" mode T}:T{ -.sp -\fBtest\fP +\fBtest\fR T}:T{ -.sp -\fBbench\fP +\fBbench\fR T} .TE .sp .sp -Dependencies use the \fBdev\fP/\fBrelease\fP profiles. +Dependencies use the \fBdev\fR/\fBrelease\fR 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, +Unit tests are separate executable artifacts which use the \fBtest\fR/\fBbench\fR +profiles. Example targets are built the same as with \fBcargo build\fR (using the +\fBdev\fR/\fBrelease\fR profiles) unless you are building them with the test harness +(by setting \fBtest = true\fR in the manifest or using the \fB\-\-example\fR flag) in +which case they use the \fBtest\fR/\fBbench\fR profiles. Library targets are built +with the \fBdev\fR/\fBrelease\fR 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 +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Execute all the unit and integration tests of the current package: .sp -.if n .RS 4 +.RS 4 .nf cargo test .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Run only tests whose names match against a filter string: +\h'-04' 2.\h'+01'Run only tests whose names match against a filter string: .sp -.if n .RS 4 +.RS 4 .nf cargo test name_filter .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Run only a specific test within a specific integration test: +\h'-04' 3.\h'+01'Run only a specific test within a specific integration test: .sp -.if n .RS 4 +.RS 4 .nf cargo test \-\-test int_test_name \-\- modname::test_name .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-bench\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-bench\fR(1) diff --git a/src/etc/man/cargo-tree.1 b/src/etc/man/cargo-tree.1 index 70179add29d..73f27c6eee0 100644 --- a/src/etc/man/cargo-tree.1 +++ b/src/etc/man/cargo-tree.1 @@ -1,43 +1,17 @@ '\" t -.\" Title: cargo-tree -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-TREE" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-TREE" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-tree \- Display a tree visualization of a dependency graph .SH "SYNOPSIS" -.sp -\fBcargo tree [\fIOPTIONS\fP]\fP +\fBcargo tree\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp This command will display a tree of dependencies to the terminal. An example of a simple project that depends on the "rand" package: .sp -.if n .RS 4 +.RS 4 .nf myproject v0.1.0 (/myproject) `\-\- rand v0.7.3 @@ -53,17 +27,17 @@ myproject v0.1.0 (/myproject) [build\-dependencies] `\-\- cc v1.0.50 .fi -.if n .RE +.RE .sp -Packages marked with \fB(*)\fP have been "de\-duplicated". The dependencies for the +Packages marked with \fB(*)\fR have been "de\-duplicated". The dependencies for the package have already been shown elswhere in the graph, and so are not -repeated. Use the \fB\-\-no\-dedupe\fP option to repeat the duplicates. +repeated. Use the \fB\-\-no\-dedupe\fR option to repeat the duplicates. .sp -The \fB\-e\fP flag can be used to select the dependency kinds to display. The +The \fB\-e\fR flag can be used to select the dependency kinds to display. The "features" kind changes the output to display the features enabled by -each dependency. For example, \fBcargo tree \-e features\fP: +each dependency. For example, \fBcargo tree \-e features\fR: .sp -.if n .RS 4 +.RS 4 .nf myproject v0.1.0 (/myproject) `\-\- log feature "serde" @@ -72,41 +46,43 @@ myproject v0.1.0 (/myproject) `\-\- cfg\-if feature "default" `\-\- cfg\-if v0.1.10 .fi -.if n .RE +.RE .sp -In this tree, \fBmyproject\fP depends on \fBlog\fP with the \fBserde\fP feature. \fBlog\fP in -turn depends on \fBcfg\-if\fP with "default" features. When using \fB\-e features\fP it -can be helpful to use \fB\-i\fP flag to show how the features flow into a package. +In this tree, \fBmyproject\fR depends on \fBlog\fR with the \fBserde\fR feature. \fBlog\fR in +turn depends on \fBcfg\-if\fR with "default" features. When using \fB\-e features\fR it +can be helpful to use \fB\-i\fR flag to show how the features flow into a package. See the examples below for more detail. .SH "OPTIONS" .SS "Tree Options" .sp -\fB\-i\fP \fISPEC\fP, \fB\-\-invert\fP \fISPEC\fP +\fB\-i\fR \fIspec\fR, +\fB\-\-invert\fR \fIspec\fR .RS 4 Show the reverse dependencies for the given package. This flag will invert the tree and display the packages that depend on the given package. .sp -Note that in a workspace, by default it will only display the package\(cqs +Note that in a workspace, by default it will only display the package's reverse dependencies inside the tree of the workspace member in the current -directory. The \fB\-\-workspace\fP flag can be used to extend it so that it will -show the package\(cqs reverse dependencies across the entire workspace. The \fB\-p\fP -flag can be used to display the package\(cqs reverse dependencies only with the -subtree of the package given to \fB\-p\fP. +directory. The \fB\-\-workspace\fR flag can be used to extend it so that it will +show the package's reverse dependencies across the entire workspace. The \fB\-p\fR +flag can be used to display the package's reverse dependencies only with the +subtree of the package given to \fB\-p\fR\&. .RE .sp -\fB\-\-no\-dedupe\fP +\fB\-\-no\-dedupe\fR .RS 4 -Do not de\-duplicate repeated dependencies. Usually, when a package has -already displayed its dependencies, further occurrences will not -re\-display its dependencies, and will include a \fB(*)\fP to indicate it has -already been shown. This flag will cause those duplicates to be repeated. +Do not de\-duplicate repeated dependencies. Usually, when a package has already +displayed its dependencies, further occurrences will not re\-display its +dependencies, and will include a \fB(*)\fR to indicate it has already been shown. +This flag will cause those duplicates to be repeated. .RE .sp -\fB\-d\fP, \fB\-\-duplicates\fP +\fB\-d\fR, +\fB\-\-duplicates\fR .RS 4 -Show only dependencies which come in multiple versions (implies -\fB\-\-invert\fP). When used with the \fB\-p\fP flag, only shows duplicates within -the subtree of the given package. +Show only dependencies which come in multiple versions (implies \fB\-\-invert\fR). +When used with the \fB\-p\fR flag, only shows duplicates within the subtree of the +given package. .sp It can be beneficial for build times and executable sizes to avoid building that same package multiple times. This flag can help identify the offending @@ -115,120 +91,64 @@ duplicate with the older version can be updated to the newer version so that only one instance is built. .RE .sp -\fB\-e\fP \fIKINDS\fP, \fB\-\-edges\fP \fIKINDS\fP +\fB\-e\fR \fIkinds\fR, +\fB\-\-edges\fR \fIkinds\fR .RS 4 The dependency kinds to display. Takes a comma separated list of values: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBall\fP — Show all edge kinds. +\h'-04'\(bu\h'+02'\fBall\fR \[em] Show all edge kinds. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnormal\fP — Show normal dependencies. +\h'-04'\(bu\h'+02'\fBnormal\fR \[em] Show normal dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBbuild\fP — Show build dependencies. +\h'-04'\(bu\h'+02'\fBbuild\fR \[em] Show build dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBdev\fP — Show development dependencies. +\h'-04'\(bu\h'+02'\fBdev\fR \[em] Show development dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBfeatures\fP — Show features enabled by each dependency. If this is -the only kind given, then it will automatically include the other -dependency kinds. +\h'-04'\(bu\h'+02'\fBfeatures\fR \[em] Show features enabled by each dependency. If this is the only +kind given, then it will automatically include the other dependency kinds. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBno\-normal\fP — Do not include normal dependencies. +\h'-04'\(bu\h'+02'\fBno\-normal\fR \[em] Do not include normal dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBno\-build\fP — Do not include build dependencies. +\h'-04'\(bu\h'+02'\fBno\-build\fR \[em] Do not include build dependencies. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBno\-dev\fP — Do not include development dependencies. +\h'-04'\(bu\h'+02'\fBno\-dev\fR \[em] Do not include development dependencies. .RE .sp -The \fBno\-\fP prefixed options cannot be mixed with the other dependency kinds. +The \fBno\-\fR prefixed options cannot be mixed with the other dependency kinds. .sp -The default is \fBnormal,build,dev\fP. +The default is \fBnormal,build,dev\fR\&. .RE .sp -\fB\-\-target\fP \fITRIPLE\fP +\fB\-\-target\fR \fItriple\fR .RS 4 -Filter dependencies matching the given target\-triple. -The default is the host platform. Use the value \fBall\fP to include \fBall\fP -targets. +Filter dependencies matching the given target\-triple. The default is the host +platform. Use the value \fBall\fR to include \fIall\fR targets. .RE .SS "Tree Formatting Options" .sp -\fB\-\-charset\fP \fICHARSET\fP +\fB\-\-charset\fR \fIcharset\fR .RS 4 Chooses the character set to use for the tree. Valid values are "utf8" or "ascii". Default is "utf8". .RE .sp -\fB\-f\fP \fIFORMAT\fP, \fB\-\-format\fP \fIFORMAT\fP +\fB\-f\fR \fIformat\fR, +\fB\-\-format\fR \fIformat\fR .RS 4 Set the format string for each package. The default is "{p}". .sp @@ -236,368 +156,257 @@ This is an arbitrary string which will be used to display each package. The foll strings will be replaced with the corresponding value: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{p}\fP — The package name. +\h'-04'\(bu\h'+02'\fB{p}\fR \[em] The package name. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{l}\fP — The package license. +\h'-04'\(bu\h'+02'\fB{l}\fR \[em] The package license. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{r}\fP — The package repository URL. +\h'-04'\(bu\h'+02'\fB{r}\fR \[em] The package repository URL. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB{f}\fP — Comma\-separated list of package features that are enabled. +\h'-04'\(bu\h'+02'\fB{f}\fR \[em] Comma\-separated list of package features that are enabled. .RE .RE .sp -\fB\-\-prefix\fP \fIPREFIX\fP +\fB\-\-prefix\fR \fIprefix\fR .RS 4 -Sets how each line is displayed. The \fIPREFIX\fP value can be one of: +Sets how each line is displayed. The \fIprefix\fR value can be one of: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBindent\fP (default) — Shows each line indented as a tree. +\h'-04'\(bu\h'+02'\fBindent\fR (default) \[em] Shows each line indented as a tree. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBdepth\fP — Show as a list, with the numeric depth printed before each entry. +\h'-04'\(bu\h'+02'\fBdepth\fR \[em] Show as a list, with the numeric depth printed before each entry. .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBnone\fP — Show as a flat list. +\h'-04'\(bu\h'+02'\fBnone\fR \[em] Show as a flat list. .RE .RE .SS "Package Selection" -.sp By default, when no package selection options are given, the packages selected depend on the selected manifest file (based on the current working directory if -\fB\-\-manifest\-path\fP is not given). If the manifest is the root of a workspace then +\fB\-\-manifest\-path\fR is not given). If the manifest is the root of a workspace then the workspaces default members are selected, otherwise only the package defined by the manifest will be selected. .sp The default members of a workspace can be set explicitly with the -\fBworkspace.default\-members\fP key in the root manifest. If this is not set, a +\fBworkspace.default\-members\fR key in the root manifest. If this is not set, a virtual workspace will include all workspace members (equivalent to passing -\fB\-\-workspace\fP), and a non\-virtual workspace will include only the root crate itself. +\fB\-\-workspace\fR), and a non\-virtual workspace will include only the root crate itself. .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 -Display only the specified packages. See \fBcargo\-pkgid\fP(1) for the +Display only the specified packages. See \fBcargo\-pkgid\fR(1) for the SPEC format. This flag may be specified multiple times. .RE .sp -\fB\-\-workspace\fP +\fB\-\-workspace\fR .RS 4 Display all members in the workspace. .RE .sp -\fB\-\-exclude\fP \fISPEC\fP... +\fB\-\-exclude\fR \fISPEC\fR\&... .RS 4 Exclude the specified packages. Must be used in conjunction with the -\fB\-\-workspace\fP flag. This flag may be specified multiple times. +\fB\-\-workspace\fR flag. This flag may be specified multiple times. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE -.SS "Feature Selection" .sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR +.RS 4 +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. +.RE +.SS "Feature Selection" The feature flags allow you to control the enabled features for the "current" package. The "current" package is the package in the current directory, or the -one specified in \fB\-\-manifest\-path\fP. If running in the root of a virtual +one specified in \fB\-\-manifest\-path\fR\&. If running in the root of a virtual workspace, then the default features are selected for all workspace members, -or all features if \fB\-\-all\-features\fP is specified. +or all features if \fB\-\-all\-features\fR is specified. .sp -When no feature options are given, the \fBdefault\fP feature is activated for +When no feature options are given, the \fBdefault\fR feature is activated for every selected package. .sp -\fB\-\-features\fP \fIFEATURES\fP +\fB\-\-features\fR \fIfeatures\fR .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. This flag may be +apply to the current directory's package. Features of direct dependencies +may be enabled with \fB/\fR syntax. This flag may be specified multiple times, which enables all specified features. .RE .sp -\fB\-\-all\-features\fP +\fB\-\-all\-features\fR .RS 4 Activate all available features of all selected packages. .RE .sp -\fB\-\-no\-default\-features\fP +\fB\-\-no\-default\-features\fR .RS 4 -Do not activate the \fBdefault\fP feature of the current directory\(cqs -package. +Do not activate the \fBdefault\fR feature of the current directory's package. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .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 -.sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-Z\fR \fIflag\fR .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 -.sp -\fB\-\-offline\fP -.RS 4 -Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible. -.sp -Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going -offline. -.sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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 tree for the package in the current directory: +\h'-04' 1.\h'+01'Display the tree for the package in the current directory: .sp -.if n .RS 4 +.RS 4 .nf cargo tree .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Display all the packages that depend on the \fBsyn\fP package: +\h'-04' 2.\h'+01'Display all the packages that depend on the \fBsyn\fR package: .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-i syn .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Show the features enabled on each package: +\h'-04' 3.\h'+01'Show the features enabled on each package: .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-\-format "{p} {f}" .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 4.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 4." 4.2 -.\} -Show all packages that are built multiple times. This can happen if multiple +\h'-04' 4.\h'+01'Show all packages that are built multiple times. This can happen if multiple semver\-incompatible versions appear in the tree (like 1.0.0 and 2.0.0). .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-d .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 5.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 5." 4.2 -.\} -Explain why features are enabled for the \fBsyn\fP package: +\h'-04' 5.\h'+01'Explain why features are enabled for the \fBsyn\fR package: .sp -.if n .RS 4 +.RS 4 .nf cargo tree \-e features \-i syn .fi -.if n .RE +.RE .sp -The \fB\-e features\fP flag is used to show features. The \fB\-i\fP flag is used to -invert the graph so that it displays the packages that depend on \fBsyn\fP. An +The \fB\-e features\fR flag is used to show features. The \fB\-i\fR flag is used to +invert the graph so that it displays the packages that depend on \fBsyn\fR\&. An example of what this would display: .sp -.if n .RS 4 +.RS 4 .nf syn v1.0.17 |\-\- syn feature "clone\-impls" @@ -621,18 +430,17 @@ syn v1.0.17 |\-\- syn feature "printing" (*) `\-\- syn feature "proc\-macro" (*) .fi -.if n .RE +.RE .sp -To read this graph, you can follow the chain for each feature from the root to -see why it is included. For example, the "full" feature is added by the -\fBrustversion\fP crate which is included from \fBmyproject\fP (with the default -features), and \fBmyproject\fP is the package selected on the command\-line. All -of the other \fBsyn\fP features are added by the "default" feature ("quote" is +To read this graph, you can follow the chain for each feature from the root +to see why it is included. For example, the "full" feature is added by the +\fBrustversion\fR crate which is included from \fBmyproject\fR (with the default +features), and \fBmyproject\fR is the package selected on the command\-line. All +of the other \fBsyn\fR features are added by the "default" feature ("quote" is added by "printing" and "proc\-macro", both of which are default features). .sp -If you\(cqre having difficulty cross\-referencing the de\-duplicated \fB(*)\fP entries, -try with the \fB\-\-no\-dedupe\fP flag to get the full output. +If you're having difficulty cross\-referencing the de\-duplicated \fB(*)\fR +entries, try with the \fB\-\-no\-dedupe\fR flag to get the full output. .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-metadata\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-metadata\fR(1) diff --git a/src/etc/man/cargo-uninstall.1 b/src/etc/man/cargo-uninstall.1 index d78a5a53a36..d6743dcec18 100644 --- a/src/etc/man/cargo-uninstall.1 +++ b/src/etc/man/cargo-uninstall.1 @@ -1,233 +1,139 @@ '\" t -.\" Title: cargo-uninstall -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-UNINSTALL" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-UNINSTALL" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-uninstall \- Remove a Rust binary .SH "SYNOPSIS" -.sp -\fBcargo uninstall [\fIOPTIONS\fP] [\fISPEC\fP...]\fP +\fBcargo uninstall\fR [\fIoptions\fR] [\fIspec\fR\&...] .SH "DESCRIPTION" -.sp -This command removes a package installed with \fBcargo\-install\fP(1). The \fISPEC\fP +This command removes a package installed with \fBcargo\-install\fR(1). The \fIspec\fR argument is a package ID specification of the package to remove (see -\fBcargo\-pkgid\fP(1)). +\fBcargo\-pkgid\fR(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. +By default all binaries are removed for a crate but the \fB\-\-bin\fR and +\fB\-\-example\fR flags can be used to only remove particular binaries. .sp The installation root is determined, in order of precedence: .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fB\-\-root\fP option +\h'-04'\(bu\h'+02'\fB\-\-root\fR 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 +\h'-04'\(bu\h'+02'\fBCARGO_INSTALL_ROOT\fR 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" "" +\h'-04'\(bu\h'+02'\fBinstall.root\fR Cargo \fIconfig value\fR .RE .sp .RS 4 -.ie n \{\ -\h'-04'\(bu\h'+03'\c -.\} -.el \{\ -. sp -1 -. IP \(bu 2.3 -.\} -\fBCARGO_HOME\fP environment variable +\h'-04'\(bu\h'+02'\fBCARGO_HOME\fR 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 +\h'-04'\(bu\h'+02'\fB$HOME/.cargo\fR .RE .SH "OPTIONS" .SS "Install Options" .sp -\fB\-p\fP, \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR, +\fB\-\-package\fR \fIspec\fR\&... .RS 4 Package to uninstall. .RE .sp -\fB\-\-bin\fP \fINAME\fP... +\fB\-\-bin\fR \fIname\fR\&... .RS 4 -Only uninstall the binary \fINAME\fP. +Only uninstall the binary \fIname\fR\&. .RE .sp -\fB\-\-root\fP \fIDIR\fP +\fB\-\-root\fR \fIdir\fR .RS 4 Directory to uninstall packages from. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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. +\h'-04' 1.\h'+01'Uninstall a previously installed package. .sp -.if n .RS 4 +.RS 4 .nf cargo uninstall ripgrep .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-install\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-install\fR(1) diff --git a/src/etc/man/cargo-update.1 b/src/etc/man/cargo-update.1 index 2b321002ed4..0cf6cf2b0f8 100644 --- a/src/etc/man/cargo-update.1 +++ b/src/etc/man/cargo-update.1 @@ -1,153 +1,110 @@ '\" t -.\" Title: cargo-update -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-UPDATE" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-UPDATE" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-update \- Update dependencies as recorded in the local lock file .SH "SYNOPSIS" -.sp -\fBcargo update [\fIOPTIONS\fP]\fP +\fBcargo update\fR [\fIoptions\fR] .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). +This command will update dependencies in the \fBCargo.lock\fR file to the latest +version. It requires that the \fBCargo.lock\fR file already exists as generated +by commands such as \fBcargo\-build\fR(1) or \fBcargo\-generate\-lockfile\fR(1). .SH "OPTIONS" .SS "Update Options" .sp -\fB\-p\fP \fISPEC\fP..., \fB\-\-package\fP \fISPEC\fP... +\fB\-p\fR \fIspec\fR\&..., +\fB\-\-package\fR \fIspec\fR\&... .RS 4 Update only the specified packages. This flag may be specified -multiple times. See \fBcargo\-pkgid\fP(1) for the SPEC format. +multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format. .sp -If packages are specified with the \fB\-p\fP flag, then a conservative update of +If packages are specified with the \fB\-p\fR flag, then a conservative update of the lockfile will be performed. This means that only the dependency specified by SPEC will be updated. Its transitive dependencies will be updated only if SPEC cannot be updated without updating dependencies. All other dependencies will remain locked at their currently recorded versions. .sp -If \fB\-p\fP is not specified, all dependencies are updated. +If \fB\-p\fR is not specified, all dependencies are updated. .RE .sp -\fB\-\-aggressive\fP +\fB\-\-aggressive\fR .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. +When used with \fB\-p\fR, dependencies of \fIspec\fR are forced to update as well. +Cannot be used with \fB\-\-precise\fR\&. .RE .sp -\fB\-\-precise\fP \fIPRECISE\fP +\fB\-\-precise\fR \fIprecise\fR .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). +When used with \fB\-p\fR, allows you to specify a specific version number to set +the package to. If the package comes from a git repository, this can be a git +revision (such as a SHA hash or tag). .RE .sp -\fB\-\-dry\-run\fP +\fB\-\-dry\-run\fR .RS 4 -Displays what would be updated, but doesn\(cqt actually write the lockfile. +Displays what would be updated, but doesn't actually write the lockfile. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -157,103 +114,74 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Update all dependencies in the lockfile: .sp -.if n .RS 4 +.RS 4 .nf cargo update .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Update only specific dependencies: +\h'-04' 2.\h'+01'Update only specific dependencies: .sp -.if n .RS 4 +.RS 4 .nf cargo update \-p foo \-p bar .fi -.if n .RE +.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: +\h'-04' 3.\h'+01'Set a specific dependency to a specific version: .sp -.if n .RS 4 +.RS 4 .nf cargo update \-p foo \-\-precise 1.2.3 .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-generate\-lockfile\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-generate\-lockfile\fR(1) diff --git a/src/etc/man/cargo-vendor.1 b/src/etc/man/cargo-vendor.1 index f94be7ce0a5..bfdec7eb3e9 100644 --- a/src/etc/man/cargo-vendor.1 +++ b/src/etc/man/cargo-vendor.1 @@ -1,69 +1,44 @@ '\" t -.\" Title: cargo-vendor -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-VENDOR" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-VENDOR" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-vendor \- Vendor all dependencies locally .SH "SYNOPSIS" -.sp -\fBcargo vendor [\fIOPTIONS\fP] [\fIPATH\fP]\fP +\fBcargo vendor\fR [\fIoptions\fR] [\fIpath\fR] .SH "DESCRIPTION" -.sp This cargo subcommand will vendor all crates.io and git dependencies for a -project into the specified directory at \fB\fP. After this command completes -the vendor directory specified by \fB\fP will contain all remote sources from +project into the specified directory at \fB\fR\&. After this command completes +the vendor directory specified by \fB\fR will contain all remote sources from dependencies specified. Additional manifests beyond the default one can be -specified with the \fB\-s\fP option. +specified with the \fB\-s\fR option. .sp -The \fBcargo vendor\fP command will also print out the configuration necessary -to use the vendored sources, which you will need to add to \fB.cargo/config.toml\fP. +The \fBcargo vendor\fR command will also print out the configuration necessary +to use the vendored sources, which you will need to add to \fB\&.cargo/config.toml\fR\&. .SH "OPTIONS" .SS "Vendor Options" .sp -\fB\-s\fP \fIMANIFEST\fP, \fB\-\-sync\fP \fIMANIFEST\fP +\fB\-s\fR \fImanifest\fR, +\fB\-\-sync\fR \fImanifest\fR .RS 4 -Specify extra \fBCargo.toml\fP manifests to workspaces which should also be +Specify extra \fBCargo.toml\fR manifests to workspaces which should also be vendored and synced to the output. .RE .sp -\fB\-\-no\-delete\fP +\fB\-\-no\-delete\fR .RS 4 -Don\(cqt delete the "vendor" directory when vendoring, but rather keep all +Don't delete the "vendor" directory when vendoring, but rather keep all existing contents of the vendor directory .RE .sp -\fB\-\-respect\-source\-config\fP +\fB\-\-respect\-source\-config\fR .RS 4 -Instead of ignoring \fB[source]\fP configuration by default in \fB.cargo/config.toml\fP +Instead of ignoring \fB[source]\fR configuration by default in \fB\&.cargo/config.toml\fR read it and use it when downloading crates from crates.io, for example .RE .sp -\fB\-\-versioned\-dirs\fP +\fB\-\-versioned\-dirs\fR .RS 4 Normally versions are only added to disambiguate multiple versions of the same package. This option causes all directories in the "vendor" directory @@ -73,187 +48,140 @@ only a subset of the packages have changed. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR +.RS 4 +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. +.RE +.sp +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Either of these flags requires that the \fBCargo.lock\fR file is +up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from +attempting to access the network to determine if it is out\-of\-date. +.sp +These may be used in environments where you want to assert that the +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network +access. +.RE +.sp +\fB\-\-offline\fR +.RS 4 +Prevents Cargo from accessing the network for any reason. Without this +flag, Cargo will stop with an error if it needs to access the network and +the network is not available. With this flag, Cargo will attempt to +proceed without the network if possible. +.sp +Beware that this may result in different dependency resolution than online +mode. Cargo will restrict itself to crates that are downloaded locally, even +if there might be a newer version as indicated in the local copy of the index. +See the \fBcargo\-fetch\fR(1) command to download dependencies before going +offline. +.sp +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .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 -.sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-Z\fR \fIflag\fR .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 -.sp -\fB\-\-offline\fP -.RS 4 -Prevents Cargo from accessing the network for any reason. Without this -flag, Cargo will stop with an error if it needs to access the network and -the network is not available. With this flag, Cargo will attempt to -proceed without the network if possible. -.sp -Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going -offline. -.sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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 -.\} -Vendor all dependencies into a local "vendor" folder +\h'-04' 1.\h'+01'Vendor all dependencies into a local "vendor" folder .sp -.if n .RS 4 +.RS 4 .nf cargo vendor .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 2.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 2." 4.2 -.\} -Vendor all dependencies into a local "third\-party/vendor" folder +\h'-04' 2.\h'+01'Vendor all dependencies into a local "third\-party/vendor" folder .sp -.if n .RS 4 +.RS 4 .nf cargo vendor third\-party/vendor .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Vendor the current workspace as well as another to "vendor" +\h'-04' 3.\h'+01'Vendor the current workspace as well as another to "vendor" .sp -.if n .RS 4 +.RS 4 .nf cargo vendor \-s ../path/to/Cargo.toml .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) \ No newline at end of file +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-verify-project.1 b/src/etc/man/cargo-verify-project.1 index 00355dad25e..ed46e464bf9 100644 --- a/src/etc/man/cargo-verify-project.1 +++ b/src/etc/man/cargo-verify-project.1 @@ -1,133 +1,89 @@ '\" t -.\" Title: cargo-verify-project -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-VERIFY\-PROJECT" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-VERIFY\-PROJECT" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-verify\-project \- Check correctness of crate manifest .SH "SYNOPSIS" -.sp -\fBcargo verify\-project [\fIOPTIONS\fP]\fP +\fBcargo verify\-project\fR [\fIoptions\fR] .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 +.RS 4 .nf {"success":"true"} .fi -.if n .RE +.RE .sp An invalid workspace will display: .sp -.if n .RS 4 +.RS 4 .nf {"invalid":"human\-readable error message"} .fi -.if n .RE +.RE .SH "OPTIONS" .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-manifest\-path\fP \fIPATH\fP +\fB\-\-manifest\-path\fR \fIpath\fR .RS 4 -Path to the \fBCargo.toml\fP file. By default, Cargo searches for the -\fBCargo.toml\fP file in the current directory or any parent directory. +Path to the \fBCargo.toml\fR file. By default, Cargo searches for the +\fBCargo.toml\fR file in the current directory or any parent directory. .RE .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -137,69 +93,54 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -The workspace is OK. +\h'-04'\(bu\h'+02'\fB0\fR: The workspace is OK. .RE .sp -1 .RS 4 -The workspace is invalid. +\h'-04'\(bu\h'+02'\fB1\fR: 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: +\h'-04' 1.\h'+01'Check the current workspace for errors: .sp -.if n .RS 4 +.RS 4 .nf cargo verify\-project .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-package\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-package\fR(1) diff --git a/src/etc/man/cargo-version.1 b/src/etc/man/cargo-version.1 index 73946405f45..cabd8b2d240 100644 --- a/src/etc/man/cargo-version.1 +++ b/src/etc/man/cargo-version.1 @@ -1,99 +1,52 @@ '\" t -.\" Title: cargo-version -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2019-09-05 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-VERSION" "1" "2019-09-05" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-VERSION" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-version \- Show version information .SH "SYNOPSIS" -.sp -\fBcargo version [\fIOPTIONS\fP]\fP +\fBcargo version\fR [\fIoptions\fR] .SH "DESCRIPTION" -.sp Displays the version of Cargo. .SH "OPTIONS" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .RS 4 Display additional version information. .RE .SH "EXAMPLES" .sp .RS 4 -.ie n \{\ -\h'-04' 1.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 1." 4.2 -.\} -Display the version: +\h'-04' 1.\h'+01'Display the version: .sp -.if n .RS 4 +.RS 4 .nf cargo version .fi -.if n .RE +.RE .RE .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: +\h'-04' 2.\h'+01'The version is also available via flags: .sp -.if n .RS 4 +.RS 4 .nf cargo \-\-version cargo \-V .fi -.if n .RE +.RE .RE .sp .RS 4 -.ie n \{\ -\h'-04' 3.\h'+01'\c -.\} -.el \{\ -. sp -1 -. IP " 3." 4.2 -.\} -Display extra version information: +\h'-04' 3.\h'+01'Display extra version information: .sp -.if n .RS 4 +.RS 4 .nf cargo \-Vv .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1) \ No newline at end of file +\fBcargo\fR(1) diff --git a/src/etc/man/cargo-yank.1 b/src/etc/man/cargo-yank.1 index e6250e976b5..95fe1e3687c 100644 --- a/src/etc/man/cargo-yank.1 +++ b/src/etc/man/cargo-yank.1 @@ -1,204 +1,144 @@ '\" t -.\" Title: cargo-yank -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO\-YANK" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO\-YANK" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo\-yank \- Remove a pushed crate from the index .SH "SYNOPSIS" -.sp -\fBcargo yank [\fIOPTIONS\fP] \-\-vers \fIVERSION\fP [\fICRATE\fP]\fP +\fBcargo yank\fR [\fIoptions\fR] \fB\-\-vers\fR \fIversion\fR [\fIcrate\fR] .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. +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. .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). +This command requires you to be authenticated with either the \fB\-\-token\fR option +or using \fBcargo\-login\fR(1). .sp If the crate name is not specified, it will use the package name from the current directory. .SH "OPTIONS" .SS "Yank Options" .sp -\fB\-\-vers\fP \fIVERSION\fP +\fB\-\-vers\fR \fIversion\fR .RS 4 The version to yank or un\-yank. .RE .sp -\fB\-\-undo\fP +\fB\-\-undo\fR .RS 4 Undo a yank, putting a version back into the index. .RE .sp -\fB\-\-token\fP \fITOKEN\fP +\fB\-\-token\fR \fItoken\fR .RS 4 API token to use when authenticating. This overrides the token stored in -the credentials file (which is created by \fBcargo\-login\fP(1)). +the credentials file (which is created by \fBcargo\-login\fR(1)). .sp -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config" " " -environment variables can be +\fICargo config\fR environment variables can be used to override the tokens stored in the credentials file. The token for -crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fP environment +crates.io may be specified with the \fBCARGO_REGISTRY_TOKEN\fR environment variable. Tokens for other registries may be specified with environment -variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fP where \fBNAME\fP is the name +variables of the form \fBCARGO_REGISTRIES_NAME_TOKEN\fR where \fBNAME\fR is the name of the registry in all capital letters. .RE .sp -\fB\-\-index\fP \fIINDEX\fP +\fB\-\-index\fR \fIindex\fR .RS 4 The URL of the registry index to use. .RE .sp -\fB\-\-registry\fP \fIREGISTRY\fP +\fB\-\-registry\fR \fIregistry\fR .RS 4 -Name of the registry to use. Registry names are defined in \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "Cargo config files" "." -If not specified, the default registry is used, which is defined by the -\fBregistry.default\fP config key which defaults to \fBcrates\-io\fP. +Name of the registry to use. Registry names are defined in \fICargo config +files\fR \&. If not specified, the default registry is used, +which is defined by the \fBregistry.default\fR config key which defaults to +\fBcrates\-io\fR\&. .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: 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: +\h'-04' 1.\h'+01'Yank a crate from the index: .sp -.if n .RS 4 +.RS 4 .nf cargo yank \-\-vers 1.0.7 foo .fi -.if n .RE +.RE .RE .SH "SEE ALSO" -.sp -\fBcargo\fP(1), \fBcargo\-login\fP(1), \fBcargo\-publish\fP(1) \ No newline at end of file +\fBcargo\fR(1), \fBcargo\-login\fR(1), \fBcargo\-publish\fR(1) diff --git a/src/etc/man/cargo.1 b/src/etc/man/cargo.1 index aec7e552a22..22010483eb4 100644 --- a/src/etc/man/cargo.1 +++ b/src/etc/man/cargo.1 @@ -1,303 +1,222 @@ '\" t -.\" Title: cargo -.\" Author: [see the "AUTHOR(S)" section] -.\" Generator: Asciidoctor 2.0.10 -.\" Date: 2020-06-25 -.\" Manual: \ \& -.\" Source: \ \& -.\" Language: English -.\" -.TH "CARGO" "1" "2020-06-25" "\ \&" "\ \&" -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.ss \n[.ss] 0 +.TH "CARGO" "1" .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 < > -.\} +.ss \n[.ss] 0 .SH "NAME" cargo \- The Rust package manager .SH "SYNOPSIS" -.sp -\fBcargo [\fIOPTIONS\fP] \fICOMMAND\fP [\fIARGS\fP]\fP +\fBcargo\fR [\fIoptions\fR] \fIcommand\fR [\fIargs\fR] .br -\fBcargo [\fIOPTIONS\fP] \-\-version\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-version\fR .br -\fBcargo [\fIOPTIONS\fP] \-\-list\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-list\fR .br -\fBcargo [\fIOPTIONS\fP] \-\-help\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-help\fR .br -\fBcargo [\fIOPTIONS\fP] \-\-explain \fICODE\fP\fP +\fBcargo\fR [\fIoptions\fR] \fB\-\-explain\fR \fIcode\fR .SH "DESCRIPTION" -.sp This program is a package manager and build tool for the Rust language, -available at \c -.URL "https://rust\-lang.org" "" "." +available at \&. .SH "COMMANDS" .SS "Build Commands" +\fBcargo\-bench\fR(1) +.br +\ \ \ \ Execute benchmarks of a package. .sp -\fBcargo\-bench\fP(1) -.RS 4 -Execute benchmarks of a package. -.RE -.sp -\fBcargo\-build\fP(1) -.RS 4 -Compile a package. -.RE +\fBcargo\-build\fR(1) +.br +\ \ \ \ Compile a package. .sp -\fBcargo\-check\fP(1) -.RS 4 -Check a local package and all of its dependencies for errors. -.RE +\fBcargo\-check\fR(1) +.br +\ \ \ \ Check a local package and all of its dependencies for errors. .sp -\fBcargo\-clean\fP(1) -.RS 4 -Remove artifacts that Cargo has generated in the past. -.RE +\fBcargo\-clean\fR(1) +.br +\ \ \ \ Remove artifacts that Cargo has generated in the past. .sp -\fBcargo\-doc\fP(1) -.RS 4 -Build a package\(cqs documentation. -.RE +\fBcargo\-doc\fR(1) +.br +\ \ \ \ Build a package's documentation. .sp -\fBcargo\-fetch\fP(1) -.RS 4 -Fetch dependencies of a package from the network. -.RE +\fBcargo\-fetch\fR(1) +.br +\ \ \ \ Fetch dependencies of a package from the network. .sp -\fBcargo\-fix\fP(1) -.RS 4 -Automatically fix lint warnings reported by rustc. -.RE +\fBcargo\-fix\fR(1) +.br +\ \ \ \ Automatically fix lint warnings reported by rustc. .sp -\fBcargo\-run\fP(1) -.RS 4 -Run a binary or example of the local package. -.RE +\fBcargo\-run\fR(1) +.br +\ \ \ \ Run a binary or example of the local package. .sp -\fBcargo\-rustc\fP(1) -.RS 4 -Compile a package, and pass extra options to the compiler. -.RE +\fBcargo\-rustc\fR(1) +.br +\ \ \ \ Compile a package, and pass extra options to the compiler. .sp -\fBcargo\-rustdoc\fP(1) -.RS 4 -Build a package\(cqs documentation, using specified custom flags. -.RE +\fBcargo\-rustdoc\fR(1) +.br +\ \ \ \ Build a package's documentation, using specified custom flags. .sp -\fBcargo\-test\fP(1) -.RS 4 -Execute unit and integration tests of a package. -.RE +\fBcargo\-test\fR(1) +.br +\ \ \ \ Execute unit and integration tests of a package. .SS "Manifest Commands" +\fBcargo\-generate\-lockfile\fR(1) +.br +\ \ \ \ Generate \fBCargo.lock\fR for a project. .sp -\fBcargo\-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 +\fBcargo\-locate\-project\fR(1) +.br +\ \ \ \ Print a JSON representation of a \fBCargo.toml\fR file's location. .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 +\fBcargo\-metadata\fR(1) +.br +\ \ \ \ Output the resolved dependencies of a package in machine\-readable format. .sp -\fBcargo\-pkgid\fP(1) -.RS 4 -Print a fully qualified package specification. -.RE +\fBcargo\-pkgid\fR(1) +.br +\ \ \ \ Print a fully qualified package specification. .sp -\fBcargo\-tree\fP(1) -.RS 4 -Display a tree visualization of a dependency graph. -.RE +\fBcargo\-tree\fR(1) +.br +\ \ \ \ Display a tree visualization of a dependency graph. .sp -\fBcargo\-update\fP(1) -.RS 4 -Update dependencies as recorded in the local lock file. -.RE +\fBcargo\-update\fR(1) +.br +\ \ \ \ Update dependencies as recorded in the local lock file. .sp -\fBcargo\-vendor\fP(1) -.RS 4 -Vendor all dependencies locally. -.RE +\fBcargo\-vendor\fR(1) +.br +\ \ \ \ Vendor all dependencies locally. .sp -\fBcargo\-verify\-project\fP(1) -.RS 4 -Check correctness of crate manifest. -.RE +\fBcargo\-verify\-project\fR(1) +.br +\ \ \ \ Check correctness of crate manifest. .SS "Package Commands" +\fBcargo\-init\fR(1) +.br +\ \ \ \ Create a new Cargo package in an existing directory. .sp -\fBcargo\-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 +\fBcargo\-install\fR(1) +.br +\ \ \ \ Build and install a Rust binary. .sp -\fBcargo\-new\fP(1) -.RS 4 -Create a new Cargo package. -.RE +\fBcargo\-new\fR(1) +.br +\ \ \ \ Create a new Cargo package. .sp -\fBcargo\-search\fP(1) -.RS 4 -Search packages in crates.io. -.RE +\fBcargo\-search\fR(1) +.br +\ \ \ \ Search packages in crates.io. .sp -\fBcargo\-uninstall\fP(1) -.RS 4 -Remove a Rust binary. -.RE +\fBcargo\-uninstall\fR(1) +.br +\ \ \ \ Remove a Rust binary. .SS "Publishing Commands" +\fBcargo\-login\fR(1) +.br +\ \ \ \ Save an API token from the registry locally. .sp -\fBcargo\-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 +\fBcargo\-owner\fR(1) +.br +\ \ \ \ Manage the owners of a crate on the registry. .sp -\fBcargo\-package\fP(1) -.RS 4 -Assemble the local package into a distributable tarball. -.RE +\fBcargo\-package\fR(1) +.br +\ \ \ \ Assemble the local package into a distributable tarball. .sp -\fBcargo\-publish\fP(1) -.RS 4 -Upload a package to the registry. -.RE +\fBcargo\-publish\fR(1) +.br +\ \ \ \ Upload a package to the registry. .sp -\fBcargo\-yank\fP(1) -.RS 4 -Remove a pushed crate from the index. -.RE +\fBcargo\-yank\fR(1) +.br +\ \ \ \ Remove a pushed crate from the index. .SS "General Commands" +\fBcargo\-help\fR(1) +.br +\ \ \ \ Display help information about Cargo. .sp -\fBcargo\-help\fP(1) -.RS 4 -Display help information about Cargo. -.RE -.sp -\fBcargo\-version\fP(1) -.RS 4 -Show version information. -.RE +\fBcargo\-version\fR(1) +.br +\ \ \ \ Show version information. .SH "OPTIONS" .SS "Special Options" .sp -\fB\-V\fP, \fB\-\-version\fP +\fB\-V\fR, +\fB\-\-version\fR .RS 4 -Print version info and exit. If used with \fB\-\-verbose\fP, prints extra +Print version info and exit. If used with \fB\-\-verbose\fR, prints extra information. .RE .sp -\fB\-\-list\fP +\fB\-\-list\fR .RS 4 -List all installed Cargo subcommands. If used with \fB\-\-verbose\fP, prints -extra information. +List all installed Cargo subcommands. If used with \fB\-\-verbose\fR, prints extra +information. .RE .sp -\fB\-\-explain \fICODE\fP\fP +\fB\-\-explain\fR \fIcode\fR .RS 4 -Run \fBrustc \-\-explain CODE\fP which will print out a detailed explanation of -an error message (for example, \fBE0004\fP). +Run \fBrustc \-\-explain CODE\fR which will print out a detailed explanation of an +error message (for example, \fBE0004\fR). .RE .SS "Display Options" .sp -\fB\-v\fP, \fB\-\-verbose\fP +\fB\-v\fR, +\fB\-\-verbose\fR .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" "." +May also be specified with the \fBterm.verbose\fR +\fIconfig value\fR \&. .RE .sp -\fB\-q\fP, \fB\-\-quiet\fP +\fB\-q\fR, +\fB\-\-quiet\fR .RS 4 No output printed to stdout. .RE .sp -\fB\-\-color\fP \fIWHEN\fP +\fB\-\-color\fR \fIwhen\fR .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 +\h'-04'\(bu\h'+02'\fBauto\fR (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. +\h'-04'\(bu\h'+02'\fBalways\fR: 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. +\h'-04'\(bu\h'+02'\fBnever\fR: 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" "." +May also be specified with the \fBterm.color\fR +\fIconfig value\fR \&. .RE .SS "Manifest Options" .sp -\fB\-\-frozen\fP, \fB\-\-locked\fP +\fB\-\-frozen\fR, +\fB\-\-locked\fR .RS 4 -Either of these flags requires that the \fBCargo.lock\fP file is +Either of these flags requires that the \fBCargo.lock\fR file is up\-to\-date. If the lock file is missing, or it needs to be updated, Cargo will -exit with an error. The \fB\-\-frozen\fP flag also prevents Cargo from +exit with an error. The \fB\-\-frozen\fR flag also prevents Cargo from attempting to access the network to determine if it is out\-of\-date. .sp These may be used in environments where you want to assert that the -\fBCargo.lock\fP file is up\-to\-date (such as a CI build) or want to avoid network +\fBCargo.lock\fR file is up\-to\-date (such as a CI build) or want to avoid network access. .RE .sp -\fB\-\-offline\fP +\fB\-\-offline\fR .RS 4 Prevents Cargo from accessing the network for any reason. Without this flag, Cargo will stop with an error if it needs to access the network and @@ -307,207 +226,145 @@ proceed without the network if possible. Beware that this may result in different dependency resolution than online mode. Cargo will restrict itself to crates that are downloaded locally, even if there might be a newer version as indicated in the local copy of the index. -See the \fBcargo\-fetch\fP(1) command to download dependencies before going +See the \fBcargo\-fetch\fR(1) command to download dependencies before going offline. .sp -May also be specified with the \fBnet.offline\fP \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "config value" "." +May also be specified with the \fBnet.offline\fR \fIconfig value\fR \&. .RE .SS "Common Options" .sp -\fB+TOOLCHAIN\fP +\fB+\fR\fItoolchain\fR .RS 4 -If Cargo has been installed with rustup, and the first argument to \fBcargo\fP -begins with \fB+\fP, it will be interpreted as a rustup toolchain name (such -as \fB+stable\fP or \fB+nightly\fP). -See the \c -.URL "https://github.com/rust\-lang/rustup/" "rustup documentation" +If Cargo has been installed with rustup, and the first argument to \fBcargo\fR +begins with \fB+\fR, it will be interpreted as a rustup toolchain name (such +as \fB+stable\fR or \fB+nightly\fR). +See the \fIrustup documentation\fR for more information about how toolchain overrides work. .RE .sp -\fB\-h\fP, \fB\-\-help\fP +\fB\-h\fR, +\fB\-\-help\fR .RS 4 Prints help information. .RE .sp -\fB\-Z\fP \fIFLAG\fP... +\fB\-Z\fR \fIflag\fR .RS 4 -Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fP for -details. +Unstable (nightly\-only) flags to Cargo. Run \fBcargo \-Z help\fR for details. .RE .SH "ENVIRONMENT" -.sp -See \c -.URL "https://doc.rust\-lang.org/cargo/reference/environment\-variables.html" "the reference" " " -for +See \fIthe reference\fR for details on environment variables that Cargo reads. .SH "EXIT STATUS" .sp -0 .RS 4 -Cargo succeeded. +\h'-04'\(bu\h'+02'\fB0\fR: Cargo succeeded. .RE .sp -101 .RS 4 -Cargo failed to complete. +\h'-04'\(bu\h'+02'\fB101\fR: Cargo failed to complete. .RE .SH "FILES" +\fB~/.cargo/\fR +.br +\ \ \ \ Default location for Cargo's "home" directory where it +stores various files. The location can be changed with the \fBCARGO_HOME\fR +environment variable. .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. -.RE -.sp -\fB$CARGO_HOME/bin/\fP -.RS 4 -Binaries installed by \fBcargo\-install\fP(1) will be located here. If using +\fB$CARGO_HOME/bin/\fR +.br +\ \ \ \ Binaries installed by \fBcargo\-install\fR(1) will be located here. If using rustup, executables distributed with Rust are also located here. -.RE .sp -\fB$CARGO_HOME/config.toml\fP -.RS 4 -The global configuration file. See \c -.URL "https://doc.rust\-lang.org/cargo/reference/config.html" "the reference" +\fB$CARGO_HOME/config.toml\fR +.br +\ \ \ \ The global configuration file. See \fIthe reference\fR for more information about configuration files. -.RE .sp -\fB.cargo/config.toml\fP -.RS 4 -Cargo automatically searches for a file named \fB.cargo/config.toml\fP in the +\fB\&.cargo/config.toml\fR +.br +\ \ \ \ Cargo automatically searches for a file named \fB\&.cargo/config.toml\fR in the current directory, and all parent directories. These configuration files will be merged with the global configuration file. -.RE .sp -\fB$CARGO_HOME/credentials.toml\fP -.RS 4 -Private authentication information for logging in to a registry. -.RE +\fB$CARGO_HOME/credentials.toml\fR +.br +\ \ \ \ Private authentication information for logging in to a registry. .sp -\fB$CARGO_HOME/registry/\fP -.RS 4 -This directory contains cached downloads of the registry index and any +\fB$CARGO_HOME/registry/\fR +.br +\ \ \ \ 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 +\fB$CARGO_HOME/git/\fR +.br +\ \ \ \ This directory contains cached downloads of git dependencies. .sp -Please note that the internal structure of the \fB$CARGO_HOME\fP directory is not +Please note that the internal structure of the \fB$CARGO_HOME\fR directory is not stable yet and may be subject to change. .SH "EXAMPLES" .sp .RS 4 -.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 +\h'-04' 1.\h'+01'Build a local package and all of its dependencies: +.sp +.RS 4 .nf cargo build .fi -.if n .RE .RE +.RE +.sp +.RS 4 +\h'-04' 2.\h'+01'Build a package with optimizations: .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 cargo build \-\-release .fi -.if n .RE +.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 +\h'-04' 3.\h'+01'Run tests for a cross\-compiled target: +.sp +.RS 4 .nf cargo test \-\-target i686\-unknown\-linux\-gnu .fi -.if n .RE .RE +.RE +.sp +.RS 4 +\h'-04' 4.\h'+01'Create a new package that builds an executable: .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 cargo new foobar .fi -.if n .RE .RE +.RE +.sp +.RS 4 +\h'-04' 5.\h'+01'Create a package in the current directory: .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 mkdir foo && cd foo cargo init . .fi -.if n .RE +.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 +\h'-04' 6.\h'+01'Learn about a command's options and usage: +.sp +.RS 4 .nf cargo help clean .fi -.if n .RE +.RE .RE .SH "BUGS" -.sp -See \c -.URL "https://github.com/rust\-lang/cargo/issues" "" " " -for issues. +See for issues. .SH "SEE ALSO" -.sp -\fBrustc\fP(1), \fBrustdoc\fP(1) \ No newline at end of file +\fBrustc\fR(1), \fBrustdoc\fR(1) From 3134eef059dfbeb689317e2e7064fa3bdf8bfd48 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 1 Aug 2020 09:38:43 -0700 Subject: [PATCH 6/7] Docs, CI, and tools for building man pages. --- .github/workflows/main.yml | 3 + ci/validate-man.sh | 26 +++++ src/doc/Makefile | 28 ----- src/doc/README.md | 38 +++---- src/doc/asciidoc-extension.rb | 125 ----------------------- src/doc/build-man.sh | 29 ++++++ src/doc/src/commands/command-common.html | 18 ---- src/doc/theme/head.hbs | 5 + 8 files changed, 82 insertions(+), 190 deletions(-) create mode 100755 ci/validate-man.sh delete mode 100644 src/doc/Makefile delete mode 100644 src/doc/asciidoc-extension.rb create mode 100755 src/doc/build-man.sh delete mode 100644 src/doc/src/commands/command-common.html create mode 100644 src/doc/theme/head.hbs diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 85589469101..69ab5b41caf 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -23,6 +23,7 @@ jobs: - run: cd crates/crates-io && cargo fmt --all -- --check - run: cd crates/resolver-tests && cargo fmt --all -- --check - run: cd crates/cargo-platform && cargo fmt --all -- --check + - run: cd crates/mdman && cargo fmt --all -- --check test: runs-on: ${{ matrix.os }} @@ -65,6 +66,7 @@ jobs: - run: cargo test --features 'deny-warnings' - run: cargo test --features 'deny-warnings' -p cargo-test-support - run: cargo test -p cargo-platform + - run: cargo test --manifest-path crates/mdman/Cargo.toml resolver: runs-on: ubuntu-latest @@ -89,6 +91,7 @@ jobs: - uses: actions/checkout@v2 - run: rustup update nightly && rustup default nightly - run: rustup component add rust-docs + - run: ci/validate-man.sh - run: | mkdir mdbook curl -Lf https://github.com/rust-lang/mdBook/releases/download/v0.3.7/mdbook-v0.3.7-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook diff --git a/ci/validate-man.sh b/ci/validate-man.sh new file mode 100755 index 00000000000..293da7e4cfe --- /dev/null +++ b/ci/validate-man.sh @@ -0,0 +1,26 @@ +#!/bin/bash +# This script validates that there aren't any changes to the man pages. + +set -e + +cd src/doc + +changes=$(git status --porcelain .) +if [ -n "$changes" ] +then + echo "git directory must be clean before running this script." + exit 1 +fi + +./build-man.sh + +changes=$(git status --porcelain .) +if [ -n "$changes" ] +then + echo "Detected changes in man pages:" + echo "$changes" + echo + echo "Please run './build-man.sh' in the src/doc directory to rebuild the" + echo "man pages, and commit the changes." + exit 1 +fi diff --git a/src/doc/Makefile b/src/doc/Makefile deleted file mode 100644 index 505532d2be8..00000000000 --- a/src/doc/Makefile +++ /dev/null @@ -1,28 +0,0 @@ -# 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/man/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,man/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): man/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/README.md b/src/doc/README.md index 85da35bc84f..92bfd8a0580 100644 --- a/src/doc/README.md +++ b/src/doc/README.md @@ -1,17 +1,17 @@ # Cargo documentation -This directory contains Cargo's documentation. There are two parts, [The Cargo Book] -which is built with [mdbook] and the man pages, which are built with [Asciidoctor]. -The man pages are also included in The Cargo Book as HTML. +This directory contains Cargo's documentation. There are two parts, [The Cargo +Book] which is built with [mdbook] and the man pages, which are built with +[mdman]. [The Cargo Book]: https://doc.rust-lang.org/cargo/ +[mdBook]: https://github.com/rust-lang/mdBook +[mdman]: https://github.com/rust-lang/cargo/tree/master/crates/mdman/ ### Building the book Building the book requires [mdBook]. To get it: -[mdBook]: https://github.com/rust-lang/mdBook - ```console $ cargo install mdbook ``` @@ -35,27 +35,27 @@ every file must be linked there. ### Building the man pages -Building the man pages requires [Asciidoctor]. See the linked page for -installation instructions. It also requires the `make` build tool and `ruby`. +The man pages use a tool called [mdman] to convert markdown to a man page +format. Check out the documentation at +[`mdman/doc/`](../../crates/mdman/doc/) +for more details. -[Asciidoctor]: https://asciidoctor.org/ +The man pages are converted from a templated markdown (located in the +[`src/doc/man/`](man) +directory) to three different formats: -The source files are located in the [`src/doc/man`](man) directory. The -[`Makefile`](Makefile) is used to rebuild the man pages. It outputs the man -pages into [`src/etc/man`](../etc/man) and the HTML versions into -[`src/doc/man/generated`](man/generated). The Cargo Book has some markdown -stub files in [`src/doc/src/commands`](src/commands) which load the generated -HTML files. +1. Troff-style man pages, saved in [`src/etc/man/`](../etc/man). +2. Markdown (with some HTML) for the Cargo Book, saved in + [`src/doc/src/commands/`](src/commands). +3. Plain text (needed for embedded man pages on platforms without man such as + Windows), saved in [`src/doc/man/generated_txt/`](man/generated_txt). -To build the man pages, run `make` in the `src/doc` directory: +To rebuild the man pages, run the script `build-man.sh` in the `src/doc` directory. ```console -$ make +$ ./build-man.sh ``` -The build script uses a few Asciidoctor extensions. See -[`asciidoc-extension.rb`](asciidoc-extension.rb) for details. - ## Contributing We'd love your help with improving the documentation! Please feel free to diff --git a/src/doc/asciidoc-extension.rb b/src/doc/asciidoc-extension.rb deleted file mode 100644 index 1fc8e99d96b..00000000000 --- a/src/doc/asciidoc-extension.rb +++ /dev/null @@ -1,125 +0,0 @@ -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 = 'index.html' - else - html_target = %(#{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. 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' - target = %(../#{target}) - 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 - -# Man pages are ASCII only. Unfortunately asciidoc doesn't process these -# characters for us. The `cargo tree` manpage needs a little assistance. -class SpecialCharPostprocessor < Extensions::Postprocessor - def process document, output - if document.basebackend? 'manpage' - output = output.gsub(/│/, '|') - .gsub(/├/, '|') - .gsub(/└/, '`') - .gsub(/─/, '\-') - 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 - postprocessor SpecialCharPostprocessor -end diff --git a/src/doc/build-man.sh b/src/doc/build-man.sh new file mode 100755 index 00000000000..85f7e526de4 --- /dev/null +++ b/src/doc/build-man.sh @@ -0,0 +1,29 @@ +#!/bin/bash +# +# This script builds the Cargo man pages. +# +# The source for the man pages are located in src/doc/man/ in markdown format. +# These also are handlebars templates, see crates/mdman/README.md for details. +# +# The generated man pages are placed in the src/etc/man/ directory. The pages +# are also expanded into markdown (after being expanded by handlebars) and +# saved in the src/doc/src/commands/ directory. These are included in the +# Cargo book, which is converted to HTML by mdbook. + +set -e + +OPTIONS="--url https://doc.rust-lang.org/cargo/commands/ \ + --man rustc:1=https://doc.rust-lang.org/rustc/index.html \ + --man rustdoc:1=https://doc.rust-lang.org/rustdoc/index.html" + +cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \ + -t md -o src/commands man/cargo*.md \ + $OPTIONS + +cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \ + -t txt -o man/generated_txt man/cargo*.md \ + $OPTIONS + +cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \ + -t man -o ../etc/man man/cargo*.md \ + $OPTIONS diff --git a/src/doc/src/commands/command-common.html b/src/doc/src/commands/command-common.html deleted file mode 100644 index 93750600f27..00000000000 --- a/src/doc/src/commands/command-common.html +++ /dev/null @@ -1,18 +0,0 @@ - diff --git a/src/doc/theme/head.hbs b/src/doc/theme/head.hbs new file mode 100644 index 00000000000..062417e1111 --- /dev/null +++ b/src/doc/theme/head.hbs @@ -0,0 +1,5 @@ + From 566706e8632b7a3c3e93701283e3125df3c9f447 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 1 Aug 2020 12:22:14 -0700 Subject: [PATCH 7/7] Fix some Windows newline behavior. --- crates/mdman/src/format/md.rs | 2 +- crates/mdman/src/lib.rs | 3 +++ crates/mdman/tests/compare.rs | 2 ++ 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/crates/mdman/src/format/md.rs b/crates/mdman/src/format/md.rs index 037807eb541..4cf4728f22c 100644 --- a/crates/mdman/src/format/md.rs +++ b/crates/mdman/src/format/md.rs @@ -28,7 +28,7 @@ impl MdFormatter { impl super::Formatter for MdFormatter { fn render(&self, input: &str) -> Result { - Ok(input.to_string()) + Ok(input.replace("\r\n", "\n")) } fn render_options_start(&self) -> &'static str { diff --git a/crates/mdman/src/lib.rs b/crates/mdman/src/lib.rs index c21b9a027cc..a362ae22127 100644 --- a/crates/mdman/src/lib.rs +++ b/crates/mdman/src/lib.rs @@ -54,6 +54,9 @@ pub fn convert( Format::Text => Box::new(format::text::TextFormatter::new(url)), }; let expanded = hbs::expand(file, &*formatter)?; + // pulldown-cmark can behave a little differently with Windows newlines, + // just normalize it. + let expanded = expanded.replace("\r\n", "\n"); formatter.render(&expanded) } diff --git a/crates/mdman/tests/compare.rs b/crates/mdman/tests/compare.rs index 4a081d439b2..3e679d1278a 100644 --- a/crates/mdman/tests/compare.rs +++ b/crates/mdman/tests/compare.rs @@ -29,6 +29,8 @@ fn run(name: &str) { std::fs::write(&expected_path, result).unwrap(); } else { let expected = std::fs::read_to_string(&expected_path).unwrap(); + // Fix if Windows checked out with autocrlf. + let expected = expected.replace("\r\n", "\n"); assert_eq!(expected, result); } }