From 3f12de6cfbf72a4e025f00fbcc5ce607c3c37c7b Mon Sep 17 00:00:00 2001 From: madolchepalooza Date: Tue, 8 Feb 2022 10:36:20 +0800 Subject: [PATCH] Refactor Repo Structure --- .gitignore | 3 + .gitmodules | 3 + build-man.sh | 9 +- cargo-doc-sync | 1 + man/cargo-bench.md | 38 +- man/cargo-build.md | 7 +- man/cargo-check.md | 7 +- man/cargo-clean.md | 46 +- man/cargo-doc.md | 22 +- man/cargo-fix.md | 6 +- man/cargo-install.md | 8 +- man/cargo-metadata.md | 4 + man/cargo-package.md | 111 ++-- man/cargo-publish.md | 2 + man/cargo-report.md | 42 ++ man/cargo-run.md | 6 +- man/cargo-rustc.md | 22 +- man/cargo-rustdoc.md | 10 +- man/cargo-test.md | 18 +- man/cargo-tree.md | 14 +- man/generated_txt/cargo-bench.txt | 226 ++++--- man/generated_txt/cargo-build.txt | 232 ++++--- man/generated_txt/cargo-check.txt | 241 ++++--- man/generated_txt/cargo-clean.txt | 158 ++--- man/generated_txt/cargo-doc.txt | 242 ++++--- man/generated_txt/cargo-fetch.txt | 98 ++- man/generated_txt/cargo-fix.txt | 235 +++---- man/generated_txt/cargo-generate-lockfile.txt | 79 ++- man/generated_txt/cargo-init.txt | 38 +- man/generated_txt/cargo-install.txt | 179 +++--- man/generated_txt/cargo-locate-project.txt | 40 +- man/generated_txt/cargo-login.txt | 36 +- man/generated_txt/cargo-metadata.txt | 107 ++-- man/generated_txt/cargo-new.txt | 38 +- man/generated_txt/cargo-owner.txt | 36 +- man/generated_txt/cargo-package.txt | 270 ++++---- man/generated_txt/cargo-pkgid.txt | 79 ++- man/generated_txt/cargo-publish.txt | 147 ++--- man/generated_txt/cargo-report.txt | 34 + man/generated_txt/cargo-run.txt | 180 +++--- man/generated_txt/cargo-rustc.txt | 203 +++--- man/generated_txt/cargo-rustdoc.txt | 184 +++--- man/generated_txt/cargo-search.txt | 36 +- man/generated_txt/cargo-test.txt | 242 ++++--- man/generated_txt/cargo-tree.txt | 161 ++--- man/generated_txt/cargo-uninstall.txt | 36 +- man/generated_txt/cargo-update.txt | 79 ++- man/generated_txt/cargo-vendor.txt | 79 ++- man/generated_txt/cargo-verify-project.txt | 73 ++- man/generated_txt/cargo-yank.txt | 36 +- man/generated_txt/cargo.txt | 75 ++- man/includes/options-display.md | 19 +- man/includes/options-future-incompat.md | 6 + man/includes/options-ignore-rust-version.md | 4 + man/includes/options-jobs.md | 5 +- man/includes/options-locked.md | 27 +- man/includes/options-manifest-path.md | 3 +- man/includes/options-new.md | 2 +- man/includes/options-profile-legacy-check.md | 10 + man/includes/options-profile.md | 7 +- man/includes/options-release.md | 7 +- man/includes/options-target-dir.md | 15 +- man/includes/options-target-triple.md | 15 +- man/includes/section-environment.md | 5 +- man/includes/section-exit-status.md | 6 +- man/includes/section-features.md | 19 +- man/includes/section-package-selection.md | 36 +- man/includes/section-profiles.md | 16 - mdman/Cargo.lock | 460 +++++++++++++ mdman/Cargo.toml | 17 + mdman/README.md | 7 + mdman/build-man.sh | 7 + mdman/doc/mdman.md | 95 +++ mdman/doc/out/mdman.1 | 124 ++++ mdman/doc/out/mdman.md | 95 +++ mdman/doc/out/mdman.txt | 91 +++ mdman/src/format.rs | 20 + mdman/src/format/man.rs | 430 +++++++++++++ mdman/src/format/md.rs | 112 ++++ mdman/src/format/text.rs | 605 ++++++++++++++++++ mdman/src/hbs.rs | 217 +++++++ mdman/src/lib.rs | 121 ++++ mdman/src/main.rs | 133 ++++ mdman/src/util.rs | 44 ++ mdman/tests/compare.rs | 48 ++ mdman/tests/compare/expected/formatting.1 | 118 ++++ mdman/tests/compare/expected/formatting.md | 94 +++ mdman/tests/compare/expected/formatting.txt | 84 +++ mdman/tests/compare/expected/links.1 | 45 ++ mdman/tests/compare/expected/links.md | 56 ++ mdman/tests/compare/expected/links.txt | 40 ++ mdman/tests/compare/expected/options.1 | 94 +++ mdman/tests/compare/expected/options.md | 77 +++ mdman/tests/compare/expected/options.txt | 57 ++ mdman/tests/compare/expected/tables.1 | 108 ++++ mdman/tests/compare/expected/tables.md | 35 + mdman/tests/compare/expected/tables.txt | 45 ++ mdman/tests/compare/expected/vars.7 | 9 + mdman/tests/compare/expected/vars.md | 7 + mdman/tests/compare/expected/vars.txt | 6 + mdman/tests/compare/formatting.md | 94 +++ mdman/tests/compare/includes/links-include.md | 7 + .../tests/compare/includes/options-common.md | 14 + mdman/tests/compare/links.md | 49 ++ mdman/tests/compare/options.md | 62 ++ mdman/tests/compare/tables.md | 35 + mdman/tests/compare/vars.md | 7 + mdman/tests/invalid.rs | 34 + mdman/tests/invalid/nested.md | 6 + mdman/tests/invalid/not-inside-options.md | 5 + src/commands/cargo-bench.md | 188 +++--- src/commands/cargo-build.md | 182 +++--- src/commands/cargo-check.md | 187 +++--- src/commands/cargo-clean.md | 128 ++-- src/commands/cargo-doc.md | 194 +++--- src/commands/cargo-fetch.md | 75 +-- src/commands/cargo-fix.md | 183 +++--- src/commands/cargo-generate-lockfile.md | 60 +- src/commands/cargo-init.md | 32 +- src/commands/cargo-install.md | 144 +++-- src/commands/cargo-locate-project.md | 33 +- src/commands/cargo-login.md | 30 +- src/commands/cargo-metadata.md | 83 ++- src/commands/cargo-new.md | 32 +- src/commands/cargo-owner.md | 30 +- src/commands/cargo-package.md | 248 +++---- src/commands/cargo-pkgid.md | 60 +- src/commands/cargo-publish.md | 122 ++-- src/commands/cargo-report.md | 43 ++ src/commands/cargo-run.md | 142 ++-- src/commands/cargo-rustc.md | 156 +++-- src/commands/cargo-rustdoc.md | 146 ++--- src/commands/cargo-search.md | 30 +- src/commands/cargo-test.md | 193 +++--- src/commands/cargo-tree.md | 127 ++-- src/commands/cargo-uninstall.md | 30 +- src/commands/cargo-update.md | 60 +- src/commands/cargo-vendor.md | 60 +- src/commands/cargo-verify-project.md | 54 +- src/commands/cargo-yank.md | 30 +- src/commands/cargo.md | 57 +- 141 files changed, 7520 insertions(+), 3913 deletions(-) create mode 100644 .gitmodules create mode 160000 cargo-doc-sync create mode 100644 man/cargo-report.md create mode 100644 man/generated_txt/cargo-report.txt create mode 100644 man/includes/options-future-incompat.md create mode 100644 man/includes/options-ignore-rust-version.md create mode 100644 man/includes/options-profile-legacy-check.md delete mode 100644 man/includes/section-profiles.md create mode 100644 mdman/Cargo.lock create mode 100644 mdman/Cargo.toml create mode 100644 mdman/README.md create mode 100644 mdman/build-man.sh create mode 100644 mdman/doc/mdman.md create mode 100644 mdman/doc/out/mdman.1 create mode 100644 mdman/doc/out/mdman.md create mode 100644 mdman/doc/out/mdman.txt create mode 100644 mdman/src/format.rs create mode 100644 mdman/src/format/man.rs create mode 100644 mdman/src/format/md.rs create mode 100644 mdman/src/format/text.rs create mode 100644 mdman/src/hbs.rs create mode 100644 mdman/src/lib.rs create mode 100644 mdman/src/main.rs create mode 100644 mdman/src/util.rs create mode 100644 mdman/tests/compare.rs create mode 100644 mdman/tests/compare/expected/formatting.1 create mode 100644 mdman/tests/compare/expected/formatting.md create mode 100644 mdman/tests/compare/expected/formatting.txt create mode 100644 mdman/tests/compare/expected/links.1 create mode 100644 mdman/tests/compare/expected/links.md create mode 100644 mdman/tests/compare/expected/links.txt create mode 100644 mdman/tests/compare/expected/options.1 create mode 100644 mdman/tests/compare/expected/options.md create mode 100644 mdman/tests/compare/expected/options.txt create mode 100644 mdman/tests/compare/expected/tables.1 create mode 100644 mdman/tests/compare/expected/tables.md create mode 100644 mdman/tests/compare/expected/tables.txt create mode 100644 mdman/tests/compare/expected/vars.7 create mode 100644 mdman/tests/compare/expected/vars.md create mode 100644 mdman/tests/compare/expected/vars.txt create mode 100644 mdman/tests/compare/formatting.md create mode 100644 mdman/tests/compare/includes/links-include.md create mode 100644 mdman/tests/compare/includes/options-common.md create mode 100644 mdman/tests/compare/links.md create mode 100644 mdman/tests/compare/options.md create mode 100644 mdman/tests/compare/tables.md create mode 100644 mdman/tests/compare/vars.md create mode 100644 mdman/tests/invalid.rs create mode 100644 mdman/tests/invalid/nested.md create mode 100644 mdman/tests/invalid/not-inside-options.md create mode 100644 src/commands/cargo-report.md diff --git a/.gitignore b/.gitignore index 3155cd2..2c948b5 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ # Ignore built book book/ +semver-check/target +semver-check/Cargo.lock +mdman/target \ No newline at end of file diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..dfede35 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "cargo-doc-sync"] + path = cargo-doc-sync + url = https://github.com/madolchepalooza/cargo-doc-sync.git diff --git a/build-man.sh b/build-man.sh index 7b1330b..f6e21f5 100644 --- a/build-man.sh +++ b/build-man.sh @@ -12,20 +12,15 @@ set -e -cd "$(dirname "${BASH_SOURCE[0]}")" - 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 -- \ +cargo run --manifest-path=./mdman/Cargo.toml -- \ -t md -o src/commands man/cargo*.md \ $OPTIONS -cargo run --manifest-path=../../crates/mdman/Cargo.toml -- \ +cargo run --manifest-path=./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/cargo-doc-sync b/cargo-doc-sync new file mode 160000 index 0000000..060bcbd --- /dev/null +++ b/cargo-doc-sync @@ -0,0 +1 @@ +Subproject commit 060bcbd34e83cafd1c2db079c555220ee35e332f diff --git a/man/cargo-bench.md b/man/cargo-bench.md index b47a1a0..ded8e2b 100644 --- a/man/cargo-bench.md +++ b/man/cargo-bench.md @@ -19,9 +19,12 @@ 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`): +arguments see the output of `cargo bench -- --help` and check out the rustc +book's chapter on how tests work at +. + +As an example, this will run only the benchmark named `foo` (and skip other +similarly named benchmarks like `foobar`): cargo bench -- foo --exact @@ -43,6 +46,14 @@ function to handle running benchmarks. > running benchmarks on the stable channel, such as > [Criterion](https://crates.io/crates/criterion). +By default, `cargo bench` uses the [`bench` profile], which enables +optimizations and disables debugging information. If you need to debug a +benchmark, you can use the `--profile=dev` command-line option to switch to +the dev profile. You can then run the debug-enabled benchmark within a +debugger. + +[`bench` profile]: ../reference/profiles.html#bench + ## OPTIONS ### Benchmark Options @@ -80,6 +91,10 @@ target. {{> options-target-triple }} +{{> options-profile }} + +{{> options-ignore-rust-version }} + {{/options}} ### Output Options @@ -124,23 +139,6 @@ Rust test harness runs benchmarks serially in a single thread. {{> options-jobs }} {{/options}} -## 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 -{{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. - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-build.md b/man/cargo-build.md index d7f0447..1a06b99 100644 --- a/man/cargo-build.md +++ b/man/cargo-build.md @@ -35,6 +35,10 @@ they have `required-features` that are missing. {{> options-release }} +{{> options-profile }} + +{{> options-ignore-rust-version }} + {{/options}} ### Output Options @@ -85,10 +89,9 @@ See for more information. {{#options}} {{> options-jobs }} +{{> options-future-incompat }} {{/options}} -{{> section-profiles }} - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-check.md b/man/cargo-check.md index 316ccd9..e0020f7 100644 --- a/man/cargo-check.md +++ b/man/cargo-check.md @@ -40,7 +40,9 @@ they have `required-features` that are missing. {{> options-release }} -{{> options-profile }} +{{> options-profile-legacy-check }} + +{{> options-ignore-rust-version }} {{/options}} @@ -72,10 +74,9 @@ they have `required-features` that are missing. {{#options}} {{> options-jobs }} +{{> options-future-incompat }} {{/options}} -{{> section-profiles }} - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-clean.md b/man/cargo-clean.md index d7d5084..d856093 100644 --- a/man/cargo-clean.md +++ b/man/cargo-clean.md @@ -1,46 +1,46 @@ # cargo-clean(1) {{*set actionverb="Clean"}} -## NAME +## 名称 -cargo-clean - Remove generated artifacts +cargo-clean - 移除已生成的工件 -## SYNOPSIS +## 用法 `cargo clean` [_options_] -## DESCRIPTION +## 描述 -Remove artifacts from the target directory that Cargo has generated in the -past. +将Cargo生成的工件从生成目标目录中移除。 -With no options, `cargo clean` will delete the entire target directory. +若不添加参数，`cargo clean` 会删除整个target目录。 -## OPTIONS +## 可选参数 -### Package Selection +### 选择包 -When no packages are selected, all packages and all dependencies in the -workspace are cleaned. +若不指定包名，则清除工作目录中的所有的包和依赖 {{#options}} {{#option "`-p` _spec_..." "`--package` _spec_..." }} -Clean only the specified packages. This flag may be specified -multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format. +只清理参数指定的包中的文件。这个参数可以多次使用来指定多个包，详见 {{man "cargo-pkgid" 1}} 。 {{/option}} {{/options}} -### Clean Options +### 清理选项 {{#options}} {{#option "`--doc`" }} -This option will cause `cargo clean` to remove only the `doc` directory in -the target directory. +添加该参数后，`cargo clean`命令只会移除生成目标目录中的`doc`目录。 {{/option}} {{#option "`--release`" }} -Clean all artifacts that were built with the `release` or `bench` profiles. +移除`release`目录中的工件。 +{{/option}} + +{{#option "`--profile` _name_" }} +移除指定编译配置(__Profile__)目录中的全部工件。 {{/option}} {{> options-target-dir }} @@ -49,13 +49,13 @@ Clean all artifacts that were built with the `release` or `bench` profiles. {{/options}} -### Display Options +### 显示选项 {{#options}} {{> options-display }} {{/options}} -### Manifest Options +### 清单选项 {{#options}} {{> options-manifest-path }} @@ -69,15 +69,15 @@ Clean all artifacts that were built with the `release` or `bench` profiles. {{> section-exit-status }} -## EXAMPLES +## 示例 -1. Remove the entire target directory: +1. 移除整个生成目标目录: cargo clean -2. Remove only the release artifacts: +2. 仅移除release目录中的工件: cargo clean --release -## SEE ALSO +## 相关 {{man "cargo" 1}}, {{man "cargo-build" 1}} diff --git a/man/cargo-doc.md b/man/cargo-doc.md index 20a9c25..551adfc 100644 --- a/man/cargo-doc.md +++ b/man/cargo-doc.md @@ -22,7 +22,9 @@ is placed in `target/doc` in rustdoc's usual format. {{#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. +browser unless you define another one in the `BROWSER` environment variable +or use the [`doc.browser`](../reference/config.html#docbrowser) configuration +option. {{/option}} {{#option "`--no-deps`" }} @@ -30,7 +32,7 @@ Do not build documentation for dependencies. {{/option}} {{#option "`--document-private-items`" }} -Include non-public items in the documentation. +Include non-public items in the documentation. This will be enabled by default if documenting a binary target. {{/option}} {{/options}} @@ -50,6 +52,16 @@ flag and will always document the given target. {{#options}} {{> options-targets-lib-bin }} + +{{#option "`--example` _name_..." }} +{{actionverb}} the specified example. This flag may be specified multiple times +and supports common Unix glob patterns. +{{/option}} + +{{#option "`--examples`" }} +{{actionverb}} all example targets. +{{/option}} + {{/options}} {{> section-features }} @@ -62,6 +74,10 @@ flag and will always document the given target. {{> options-release }} +{{> options-profile }} + +{{> options-ignore-rust-version }} + {{/options}} ### Output Options @@ -94,8 +110,6 @@ flag and will always document the given target. {{> options-jobs }} {{/options}} -{{> section-profiles }} - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-fix.md b/man/cargo-fix.md index ab1e24e..2d96efd 100644 --- a/man/cargo-fix.md +++ b/man/cargo-fix.md @@ -120,7 +120,9 @@ When no target selection options are given, `cargo fix` will fix all targets {{> options-release }} -{{> options-profile }} +{{> options-profile-legacy-check }} + +{{> options-ignore-rust-version }} {{/options}} @@ -154,8 +156,6 @@ When no target selection options are given, `cargo fix` will fix all targets {{> options-jobs }} {{/options}} -{{> section-profiles }} - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-install.md b/man/cargo-install.md index 95f5500..28d7c6a 100644 --- a/man/cargo-install.md +++ b/man/cargo-install.md @@ -42,7 +42,7 @@ 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 profile (`--profile`). - The target (`--target`). Installing with `--path` will always build and install, unless there are @@ -162,8 +162,11 @@ Directory to install packages into. {{#option "`--debug`" }} Build with the `dev` profile instead the `release` profile. +See also the `--profile` option for choosing a specific profile by name. {{/option}} +{{> options-profile }} + {{/options}} ### Manifest Options @@ -182,6 +185,9 @@ Build with the `dev` profile instead the `release` profile. {{#options}} {{> options-display }} + +{{> options-message-format }} + {{/options}} {{> section-options-common }} diff --git a/man/cargo-metadata.md b/man/cargo-metadata.md index 33951fd..c1a8920 100644 --- a/man/cargo-metadata.md +++ b/man/cargo-metadata.md @@ -180,6 +180,10 @@ The output has the following format: "categories": [ "command-line-utilities" ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", /* Array of keywords from the manifest. */ "keywords": [ "cli" diff --git a/man/cargo-package.md b/man/cargo-package.md index a825299..441fa03 100644 --- a/man/cargo-package.md +++ b/man/cargo-package.md @@ -1,73 +1,80 @@ # cargo-package(1) {{*set actionverb="Package"}} +{{*set noall=true}} -## NAME +## 名称 -cargo-package - Assemble the local package into a distributable tarball +cargo-package - 将本地包打包为可分发的压缩文件 -## SYNOPSIS +## 用法 `cargo package` [_options_] -## DESCRIPTION - -This command will create a distributable, compressed `.crate` file with the -source code of the package in the current directory. The resulting file will -be stored in the `target/package` directory. This performs the following -steps: - -1. Load and check the current workspace, performing some basic checks. - - Path dependencies are not allowed unless they have a version key. Cargo - will ignore the path key for dependencies in published packages. - `dev-dependencies` do not have this restriction. -2. Create the compressed `.crate` file. - - The original `Cargo.toml` file is rewritten and normalized. - - `[patch]`, `[replace]`, and `[workspace]` sections are removed from the - manifest. - - `Cargo.lock` is automatically included if the package contains an - executable binary or example target. {{man "cargo-install" 1}} will use the - packaged lock file if the `--locked` flag is used. - - A `.cargo_vcs_info.json` file is included that contains information - about the current VCS checkout hash if available (not included with - `--allow-dirty`). -3. Extract the `.crate` file and build it to verify it can build. - - This will rebuild your package from scratch to ensure that it can be - built from a pristine state. The `--no-verify` flag can be used to skip - this step. -4. Check that build scripts did not modify any source files. - -The list of files included can be controlled with the `include` and `exclude` -fields in the manifest. - -See [the reference](../reference/publishing.html) for more details about -packaging and publishing. - -## OPTIONS - -### Package Options +## 描述 + +此命令会在当前目录创建一个可分发的，压缩过的`.crate`文件并附带其源代码。文件会存储于 +`target/package`目录中。命令的执行可分为以下步骤： + +1. 加载当前的工作空间以进行基本的检查。 + - 如果不指定依赖的版本，就不能使用路径依赖。Cargo会在发布的包中忽略路径值。但 + `dev-dependencies` 没有这一限制。 +2. 创建压缩的`.crate`文件 + - 原始的 `Cargo.toml`文件会被重写并规范化。 + - 清单中的 `[patch]`、`[replace]`、`[workspace]`段会被移除。 + - 如果包中有可执行的二进制或示例编译目标，则还会包含`Cargo.lock`文件。如果指定了 + `--locked`标志参数，{{man "cargo-install" 1}}会使用锁文件。 + - 如果可用，会通过`.cargo_vcs_info.json`文件保存当前版本控制系统的签出哈希值(__Checkout Hash__)。 + 可通过`--allow-dirty`标志参数指定不生成该文件。 +3. 解压`.crate`文件并对其进行构建，以验证其确实可以成功构建。 + - 这一步会从头开始构建，以确保可以从原始状态构建。可通过指定`--no-verify`标志参数来跳过这一步。 +4. 检查构建脚本是否会修改源代码的文件。 + +包含文件的范围可通过清单中的`include`和`exclude`字段来控制。 + +更多关于打包和发布的细节可参见[the reference](../reference/publishing.html) + +### .cargo_vcs_info.json 的格式 + +会以下面的格式生成`.cargo_vcs_info.json`文件。 + +```javascript +{ + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" +} +``` + +`path_in_vcs`会被设置为该软件包关于版本控制仓库的相对路径 + +## 可选参数 + +### 打包选项 {{#options}} {{#option "`-l`" "`--list`" }} -Print files included in a package without making one. +输出包中包含的文件(不实际进行打包)。 {{/option}} {{#option "`--no-verify`" }} -Don't verify the contents by building them. +构建包时不进行校验。 {{/option}} {{#option "`--no-metadata`" }} -Ignore warnings about a lack of human-usable metadata (such as the description -or the license). +忽略 缺少可读的元信息(如描述信息或采用的授权协议) 时产生的警告。 {{/option}} {{#option "`--allow-dirty`" }} -Allow working directories with uncommitted VCS changes to be packaged. +允许打包 在版本控制系统中仍有未提交内容 的包。 {{/option}} {{/options}} -### Compilation Options +{{> section-package-selection }} + +### 编译选项 {{#options}} @@ -79,7 +86,7 @@ Allow working directories with uncommitted VCS changes to be packaged. {{> section-features }} -### Manifest Options +### 清单选项 {{#options}} @@ -89,13 +96,13 @@ Allow working directories with uncommitted VCS changes to be packaged. {{/options}} -### Miscellaneous Options +### 混杂选项 {{#options}} {{> options-jobs }} {{/options}} -### Display Options +### 显示选项 {{#options}} {{> options-display }} @@ -107,11 +114,11 @@ Allow working directories with uncommitted VCS changes to be packaged. {{> section-exit-status }} -## EXAMPLES +## 示例 -1. Create a compressed `.crate` file of the current package: +1. 为当前包创建一个压缩好的`.crate`文件: - cargo package + cargo package -## SEE ALSO +## 相关 {{man "cargo" 1}}, {{man "cargo-publish" 1}} diff --git a/man/cargo-publish.md b/man/cargo-publish.md index 64b7bd6..13ee736 100644 --- a/man/cargo-publish.md +++ b/man/cargo-publish.md @@ -63,6 +63,8 @@ which defaults to `crates-io`. {{/options}} +{{> section-options-package }} + ### Compilation Options {{#options}} diff --git a/man/cargo-report.md b/man/cargo-report.md new file mode 100644 index 0000000..a505a01 --- /dev/null +++ b/man/cargo-report.md @@ -0,0 +1,42 @@ +# cargo-report(1) + +## NAME + +cargo-report - Generate and display various kinds of reports + +## SYNOPSIS + +`cargo report` _type_ [_options_] + +### DESCRIPTION + +Displays a report of the given _type_ - currently, only `future-incompat` is supported + +## OPTIONS + +{{#options}} + +{{#option "`--id` _id_" }} +Show the report with the specified Cargo-generated id +{{/option}} + +{{#option "`-p` _spec_..." "`--package` _spec_..." }} +Only display a report for the specified package +{{/option}} + +{{/options}} + +## EXAMPLES + +1. Display the latest future-incompat report: + + cargo report future-incompat + +2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +## SEE ALSO +[Future incompat report](../reference/future-incompat-report.html) + +{{man "cargo" 1}} diff --git a/man/cargo-run.md b/man/cargo-run.md index bd54561..b4e1d06 100644 --- a/man/cargo-run.md +++ b/man/cargo-run.md @@ -50,6 +50,10 @@ Run the specified example. {{> options-release }} +{{> options-profile }} + +{{> options-ignore-rust-version }} + {{/options}} ### Output Options @@ -86,8 +90,6 @@ Run the specified example. {{> options-jobs }} {{/options}} -{{> section-profiles }} - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-rustc.md b/man/cargo-rustc.md index c7f7457..53ed339 100644 --- a/man/cargo-rustc.md +++ b/man/cargo-rustc.md @@ -47,6 +47,25 @@ binary and library targets of the selected package. {{> options-release }} +{{#option "`--profile` _name_" }} +Build with the given profile. + +The `rustc` subcommand will treat the following named profiles with special behaviors: + +* `check` — Builds in the same way as the {{man "cargo-check" 1}} command with + the `dev` profile. +* `test` — Builds in the same way as the {{man "cargo-test" 1}} command, + enabling building in test mode which will enable tests and enable the `test` + cfg option. See [rustc + tests](https://doc.rust-lang.org/rustc/tests/index.html) for more detail. +* `bench` — Builds in the same was as the {{man "cargo-bench" 1}} command, + similar to the `test` profile. + +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} + +{{> options-ignore-rust-version }} + {{/options}} ### Output Options @@ -81,10 +100,9 @@ binary and library targets of the selected package. {{#options}} {{> options-jobs }} +{{> options-future-incompat }} {{/options}} -{{> section-profiles }} - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-rustdoc.md b/man/cargo-rustdoc.md index 958aa13..278c569 100644 --- a/man/cargo-rustdoc.md +++ b/man/cargo-rustdoc.md @@ -34,7 +34,9 @@ or the `build.rustdocflags` [config value](../reference/config.html). {{#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. +browser unless you define another one in the `BROWSER` environment variable +or use the [`doc.browser`](../reference/config.html#docbrowser) configuration +option. {{/option}} {{/options}} @@ -60,6 +62,10 @@ if its name is the same as the lib target. Binaries are skipped if they have {{> options-release }} +{{> options-profile }} + +{{> options-ignore-rust-version }} + {{/options}} ### Output Options @@ -92,8 +98,6 @@ if its name is the same as the lib target. Binaries are skipped if they have {{> options-jobs }} {{/options}} -{{> section-profiles }} - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-test.md b/man/cargo-test.md index a35b0a7..be12eaa 100644 --- a/man/cargo-test.md +++ b/man/cargo-test.md @@ -19,7 +19,8 @@ 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` and check out the rustc book's chapter on +how tests work at . As an example, this will filter for tests with `foo` in their name and run them on 3 threads in parallel: @@ -101,6 +102,10 @@ target options. {{> options-release }} +{{> options-profile }} + +{{> options-ignore-rust-version }} + {{/options}} ### Output Options @@ -148,19 +153,10 @@ includes an option to control the number of threads used: {{#options}} {{> options-jobs }} +{{> options-future-incompat }} {{/options}} -{{> 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 -`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. - {{> section-environment }} {{> section-exit-status }} diff --git a/man/cargo-tree.md b/man/cargo-tree.md index 789de41..7a6a8de 100644 --- a/man/cargo-tree.md +++ b/man/cargo-tree.md @@ -71,6 +71,15 @@ flag can be used to display the package's reverse dependencies only with the subtree of the package given to `-p`. {{/option}} +{{#option "`--prune` _spec_" }} +Prune the given package from the display of the dependency tree. +{{/option}} + +{{#option "`--depth` _depth_" }} +Maximum display depth of the dependency tree. A depth of 1 displays the direct +dependencies, for example. +{{/option}} + {{#option "`--no-dedupe`" }} Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its @@ -102,8 +111,10 @@ The dependency kinds to display. Takes a comma separated list of values: - `no-normal` — Do not include normal dependencies. - `no-build` — Do not include build dependencies. - `no-dev` — Do not include development dependencies. +- `no-proc-macro` — Do not include procedural macro dependencies. -The `no-` prefixed options cannot be mixed with the other dependency kinds. +The `normal`, `build`, `dev`, and `all` dependency kinds cannot be mixed with +`no-normal`, `no-build`, or `no-dev` dependency kinds. The default is `normal,build,dev`. {{/option}} @@ -134,6 +145,7 @@ strings will be replaced with the corresponding value: - `{l}` — The package license. - `{r}` — The package repository URL. - `{f}` — Comma-separated list of package features that are enabled. +- `{lib}` — The name, as used in a `use` statement, of the package's library. {{/option}} {{#option "`--prefix` _prefix_" }} diff --git a/man/generated_txt/cargo-bench.txt b/man/generated_txt/cargo-bench.txt index 33e2b65..9c5fe9e 100644 --- a/man/generated_txt/cargo-bench.txt +++ b/man/generated_txt/cargo-bench.txt @@ -15,8 +15,11 @@ DESCRIPTION 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): + --help and check out the rustc book's chapter on how tests work at + . + + As an example, this will run only the benchmark named foo (and skip + other similarly named benchmarks like foobar): cargo bench -- foo --exact @@ -38,6 +41,13 @@ DESCRIPTION benchmarks on the stable channel, such as Criterion . + By default, cargo bench uses the bench profile + , which + enables optimizations and disables debugging information. If you need to + debug a benchmark, you can use the --profile=dev command-line option to + switch to the dev profile. You can then run the debug-enabled benchmark + within a debugger. + OPTIONS Benchmark Options --no-run @@ -49,41 +59,33 @@ OPTIONS 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. + 选择包 + + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 - 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. + + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 -p spec..., --package spec... - Benchmark only the specified packages. See cargo-pkgid(1) for the - SPEC format. This flag may be specified multiple times and supports - common Unix glob patterns like *, ? and []. However, to avoid your - shell accidentally expanding glob patterns before Cargo handles - them, you must use single quotes or double quotes around each - pattern. + Benchmark指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 --workspace - Benchmark all members in the workspace. + Benchmark 工作区中的全体成员. --all - Deprecated alias for --workspace. + --workspace的已废弃的别名。 --exclude SPEC... - Exclude the specified packages. Must be used in conjunction with the - --workspace flag. This flag may be specified multiple times and - supports common Unix glob patterns like *, ? and []. However, to - avoid your shell accidentally expanding glob patterns before Cargo - handles them, you must use single quotes or double quotes around - each pattern. + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 Target Selection When no target selection options are given, cargo bench will build the @@ -162,50 +164,58 @@ OPTIONS Benchmark all targets. This is equivalent to specifying --lib --bins --tests --benches --examples. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 + + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 - See the features documentation - - for more details. + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Benchmark + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见build cache - documentation for more details. + + --profile name + Benchmark with the given profile. See the the reference + for more + details on profiles. + + --ignore-rust-version + Benchmark the target even if the selected Rust compiler is older + than the required Rust version as configured in the project's + rust-version field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 Display Options By default the Rust test harness hides output from benchmark execution @@ -215,25 +225,28 @@ OPTIONS 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -266,34 +279,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -316,36 +326,18 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Build and execute all the benchmarks of the current package: diff --git a/man/generated_txt/cargo-build.txt b/man/generated_txt/cargo-build.txt index cb3ccb0..ee24fcb 100644 --- a/man/generated_txt/cargo-build.txt +++ b/man/generated_txt/cargo-build.txt @@ -10,41 +10,33 @@ 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. + 选择包 + + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 + + + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 -p spec..., --package spec... - Build only the specified packages. See cargo-pkgid(1) for the SPEC - format. This flag may be specified multiple times and supports - common Unix glob patterns like *, ? and []. However, to avoid your - shell accidentally expanding glob patterns before Cargo handles - them, you must use single quotes or double quotes around each - pattern. + Build指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 --workspace - Build all members in the workspace. + Build 工作区中的全体成员. --all - Deprecated alias for --workspace. + --workspace的已废弃的别名。 --exclude SPEC... - Exclude the specified packages. Must be used in conjunction with the - --workspace flag. This flag may be specified multiple times and - supports common Unix glob patterns like *, ? and []. However, to - avoid your shell accidentally expanding glob patterns before Cargo - handles them, you must use single quotes or double quotes around - each pattern. + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 Target Selection When no target selection options are given, cargo build will build all @@ -105,54 +97,62 @@ OPTIONS Build all targets. This is equivalent to specifying --lib --bins --tests --benches --examples. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 + + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 - See the features documentation - - for more details. + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Build + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Build optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Build with the given profile. See the the reference + for more + details on profiles. + + --ignore-rust-version + Build the target even if the selected Rust compiler is older than + the required Rust version as configured in the project's + rust-version field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 --out-dir directory Copy final artifacts to this directory. @@ -165,25 +165,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -226,34 +229,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -272,42 +272,24 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Build the local package and all of its dependencies: diff --git a/man/generated_txt/cargo-check.txt b/man/generated_txt/cargo-check.txt index 430118c..d84880d 100644 --- a/man/generated_txt/cargo-check.txt +++ b/man/generated_txt/cargo-check.txt @@ -16,41 +16,33 @@ DESCRIPTION with cargo check. OPTIONS - Package Selection - By default, when no package selection options are given, the packages - selected depend on the selected manifest file (based on the current - working directory if --manifest-path is not given). If the manifest is - the root of a workspace then the workspaces default members are - selected, otherwise only the package defined by the manifest will be - selected. - - The default members of a workspace can be set explicitly with the - workspace.default-members key in the root manifest. If this is not set, - a virtual workspace will include all workspace members (equivalent to - passing --workspace), and a non-virtual workspace will include only the - root crate itself. + 选择包 + + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 + + + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 -p spec..., --package spec... - Check only the specified packages. See cargo-pkgid(1) for the SPEC - format. This flag may be specified multiple times and supports - common Unix glob patterns like *, ? and []. However, to avoid your - shell accidentally expanding glob patterns before Cargo handles - them, you must use single quotes or double quotes around each - pattern. + Check指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 --workspace - Check all members in the workspace. + Check 工作区中的全体成员. --all - Deprecated alias for --workspace. + --workspace的已废弃的别名。 --exclude SPEC... - Exclude the specified packages. Must be used in conjunction with the - --workspace flag. This flag may be specified multiple times and - supports common Unix glob patterns like *, ? and []. However, to - avoid your shell accidentally expanding glob patterns before Cargo - handles them, you must use single quotes or double quotes around - each pattern. + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 Target Selection When no target selection options are given, cargo check will check all @@ -111,82 +103,94 @@ OPTIONS Check all targets. This is equivalent to specifying --lib --bins --tests --benches --examples. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 + + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 - See the features documentation - - for more details. + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Check + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Check optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. --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. + Check with the given profile. + + As a special case, specifying the test profile will also enable + checking in test mode which will enable checking tests and enable + the test cfg option. See rustc tests + for more detail. + + See the the reference + for more + details on profiles. + + --ignore-rust-version + Check the target even if the selected Rust compiler is older than + the required Rust version as configured in the project's + rust-version field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -219,34 +223,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -265,42 +266,24 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Check the local package for errors: diff --git a/man/generated_txt/cargo-clean.txt b/man/generated_txt/cargo-clean.txt index 192217e..a1474b7 100644 --- a/man/generated_txt/cargo-clean.txt +++ b/man/generated_txt/cargo-clean.txt @@ -1,110 +1,111 @@ CARGO-CLEAN(1) -NAME - cargo-clean - Remove generated artifacts +名称 + cargo-clean - 移除已生成的工件 -SYNOPSIS +用法 cargo clean [options] -DESCRIPTION - Remove artifacts from the target directory that Cargo has generated in - the past. +描述 + 将Cargo生成的工件从生成目标目录中移除。 - With no options, cargo clean will delete the entire target directory. + 若不添加参数，cargo clean 会删除整个target目录。 -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 + 只清理参数指定的包中的文件。这个参数可以多次使用来指定多个包，详见 + cargo-pkgid(1) 。 + + 清理选项 --doc - This option will cause cargo clean to remove only the doc directory - in the target directory. + 添加该参数后，cargo + clean命令只会移除生成目标目录中的doc目录。 --release - Clean all artifacts that were built with the release or bench - profiles. + 移除release目录中的工件。 + + --profile name + 移除指定编译配置(Profile)目录中的全部工件。 --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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 --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. + 为指定架构执行 Clean + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 - This may also be specified with the build.target config value - . + 也可通过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 + + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -121,25 +122,24 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. -EXAMPLES - 1. Remove the entire target directory: +示例 + 1. 移除整个生成目标目录: cargo clean - 2. Remove only the release artifacts: + 2. 仅移除release目录中的工件: cargo clean --release -SEE ALSO +相关 cargo(1), cargo-build(1) diff --git a/man/generated_txt/cargo-doc.txt b/man/generated_txt/cargo-doc.txt index 8798744..a7387a1 100644 --- a/man/generated_txt/cargo-doc.txt +++ b/man/generated_txt/cargo-doc.txt @@ -15,49 +15,44 @@ 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. + environment variable or use the doc.browser + + configuration option. --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. + Include non-public items in the documentation. This will be enabled + by default if documenting a binary target. + + 选择包 + + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 + + + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 -p spec..., --package spec... - Document only the specified packages. See cargo-pkgid(1) for the - SPEC format. This flag may be specified multiple times and supports - common Unix glob patterns like *, ? and []. However, to avoid your - shell accidentally expanding glob patterns before Cargo handles - them, you must use single quotes or double quotes around each - pattern. + Document指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 --workspace - Document all members in the workspace. + Document 工作区中的全体成员. --all - Deprecated alias for --workspace. + --workspace的已废弃的别名。 --exclude SPEC... - Exclude the specified packages. Must be used in conjunction with the - --workspace flag. This flag may be specified multiple times and - supports common Unix glob patterns like *, ? and []. However, to - avoid your shell accidentally expanding glob patterns before Cargo - handles them, you must use single quotes or double quotes around - each pattern. + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 Target Selection When no target selection options are given, cargo doc will document all @@ -79,76 +74,94 @@ OPTIONS --bins Document all binary targets. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + --example name... + Document the specified example. This flag may be specified multiple + times and supports common Unix glob patterns. + + --examples + Document all example targets. + + 特性选择 - See the features documentation - - for more details. + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Document + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Document optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Document with the given profile. See the the reference + for more + details on profiles. + + --ignore-rust-version + Document the target even if the selected Rust compiler is older than + the required Rust version as configured in the project's + rust-version field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -181,34 +194,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -227,42 +237,18 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Build the local package documentation and its dependencies and output diff --git a/man/generated_txt/cargo-fetch.txt b/man/generated_txt/cargo-fetch.txt index f714b94..2f26643 100644 --- a/man/generated_txt/cargo-fetch.txt +++ b/man/generated_txt/cargo-fetch.txt @@ -25,73 +25,72 @@ DESCRIPTION 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. + 为指定架构执行 Fetch + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -108,15 +107,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Fetch all dependencies: diff --git a/man/generated_txt/cargo-fix.txt b/man/generated_txt/cargo-fix.txt index c2b3aa5..8a14a81 100644 --- a/man/generated_txt/cargo-fix.txt +++ b/man/generated_txt/cargo-fix.txt @@ -89,41 +89,33 @@ OPTIONS --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. + 选择包 + + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 + + + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 -p spec..., --package spec... - Fix only the specified packages. See cargo-pkgid(1) for the SPEC - format. This flag may be specified multiple times and supports - common Unix glob patterns like *, ? and []. However, to avoid your - shell accidentally expanding glob patterns before Cargo handles - them, you must use single quotes or double quotes around each - pattern. + Fix指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 --workspace - Fix all members in the workspace. + Fix 工作区中的全体成员. --all - Deprecated alias for --workspace. + --workspace的已废弃的别名。 --exclude SPEC... - Exclude the specified packages. Must be used in conjunction with the - --workspace flag. This flag may be specified multiple times and - supports common Unix glob patterns like *, ? and []. However, to - avoid your shell accidentally expanding glob patterns before Cargo - handles them, you must use single quotes or double quotes around - each pattern. + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 Target Selection When no target selection options are given, cargo fix will fix all @@ -184,82 +176,94 @@ OPTIONS Fix all targets. This is equivalent to specifying --lib --bins --tests --benches --examples. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 - See the features documentation - - for more details. + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Fix + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 - This may also be specified with the build.target config value - . + 也可通过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 + + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Fix optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. --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. + Fix with the given profile. + + As a special case, specifying the test profile will also enable + checking in test mode which will enable checking tests and enable + the test cfg option. See rustc tests + for more detail. + + See the the reference + for more + details on profiles. + + --ignore-rust-version + Fix the target even if the selected Rust compiler is older than the + required Rust version as configured in the project's rust-version + field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -292,34 +296,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -338,42 +339,18 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Apply compiler suggestions to the local package: diff --git a/man/generated_txt/cargo-generate-lockfile.txt b/man/generated_txt/cargo-generate-lockfile.txt index 835183c..b057144 100644 --- a/man/generated_txt/cargo-generate-lockfile.txt +++ b/man/generated_txt/cargo-generate-lockfile.txt @@ -17,57 +17,57 @@ DESCRIPTION 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -84,15 +84,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Create or update the lockfile for the current package or workspace: diff --git a/man/generated_txt/cargo-init.txt b/man/generated_txt/cargo-init.txt index e96abbb..8a3bcd2 100644 --- a/man/generated_txt/cargo-init.txt +++ b/man/generated_txt/cargo-init.txt @@ -30,7 +30,7 @@ OPTIONS Create a package with a library target (src/lib.rs). --edition edition - Specify the Rust edition to use. Default is 2018. Possible values: + Specify the Rust edition to use. Default is 2021. Possible values: 2015, 2018, 2021 --name name @@ -56,25 +56,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -92,15 +95,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Create a binary Cargo package in the current directory: diff --git a/man/generated_txt/cargo-install.txt b/man/generated_txt/cargo-install.txt index ce009c0..32b2c6c 100644 --- a/man/generated_txt/cargo-install.txt +++ b/man/generated_txt/cargo-install.txt @@ -51,7 +51,7 @@ DESCRIPTION o The chosen features. - o The release mode (--debug). + o The profile (--profile). o The target (--target). @@ -148,114 +148,144 @@ OPTIONS --index index The URL of the registry index to use. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 - See the features documentation - - for more details. + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Install + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 - This may also be specified with the build.target config value - . + 也可通过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 + + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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 - a new temporary folder located in the temporary directory of the - platform. - When using --path, by default it will use target directory in the - workspace of the local crate unless --target-dir is specified. + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下位于该平台临时目录下的一个新的临时文件夹。 + + 当指定 + --path标志参数时，若未指定--target-dir，则默认会使用工作区中的target目录。 --debug - Build with the dev profile instead the release profile. + Build with the dev profile instead the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Install with the given profile. See the the reference + for more + details on profiles. 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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 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. + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + Conflicts with short and json. + + o short: Emit shorter, human-readable text messages. Conflicts with + human and json. + + o json: Emit JSON messages to stdout. See the reference + + for more details. Conflicts with human and short. + + o json-diagnostic-short: Ensure the rendered field of JSON messages + contains the "short" rendering from rustc. Cannot be used with + human or short. + + o json-diagnostic-rendered-ansi: Ensure the rendered field of JSON + messages contains embedded ANSI color codes for respecting + rustc's default color scheme. Cannot be used with human or short. + + o json-render-diagnostics: Instruct Cargo to not include rustc + diagnostics in in JSON messages printed, but instead Cargo itself + should render the JSON diagnostics coming from rustc. Cargo's own + JSON diagnostics and others coming from rustc are still emitted. + Cannot be used with human or short. + Common Options +toolchain If Cargo has been installed with rustup, and the first argument to @@ -271,15 +301,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Install or upgrade a package from crates.io: diff --git a/man/generated_txt/cargo-locate-project.txt b/man/generated_txt/cargo-locate-project.txt index 6e43f93..b0478a6 100644 --- a/man/generated_txt/cargo-locate-project.txt +++ b/man/generated_txt/cargo-locate-project.txt @@ -26,31 +26,34 @@ OPTIONS o plain: Just the path. -v, --verbose - Use verbose output. May be specified twice for "very verbose" output - which includes extra output such as dependency warnings and build - script output. May also be specified with the term.verbose config - value . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 Common Options +toolchain @@ -67,15 +70,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Display the path to the manifest based on the current directory: diff --git a/man/generated_txt/cargo-login.txt b/man/generated_txt/cargo-login.txt index 9a3bb0e..aed899c 100644 --- a/man/generated_txt/cargo-login.txt +++ b/man/generated_txt/cargo-login.txt @@ -31,25 +31,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -67,15 +70,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Save the API token to disk: diff --git a/man/generated_txt/cargo-metadata.txt b/man/generated_txt/cargo-metadata.txt index 8dcd222..70abff9 100644 --- a/man/generated_txt/cargo-metadata.txt +++ b/man/generated_txt/cargo-metadata.txt @@ -175,6 +175,10 @@ OUTPUT FORMAT "categories": [ "command-line-utilities" ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", /* Array of keywords from the manifest. */ "keywords": [ "cli" @@ -302,80 +306,78 @@ OPTIONS includes all dependencies. Each package definition is intended to be an unaltered reproduction of the information within Cargo.toml. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 - See the features documentation - - for more details. + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -392,15 +394,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Output JSON about the current package: diff --git a/man/generated_txt/cargo-new.txt b/man/generated_txt/cargo-new.txt index 69ccfe3..20c950e 100644 --- a/man/generated_txt/cargo-new.txt +++ b/man/generated_txt/cargo-new.txt @@ -25,7 +25,7 @@ OPTIONS Create a package with a library target (src/lib.rs). --edition edition - Specify the Rust edition to use. Default is 2018. Possible values: + Specify the Rust edition to use. Default is 2021. Possible values: 2015, 2018, 2021 --name name @@ -51,25 +51,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -87,15 +90,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Create a binary Cargo package in the given directory: diff --git a/man/generated_txt/cargo-owner.txt b/man/generated_txt/cargo-owner.txt index 80b7b7a..8e0ad50 100644 --- a/man/generated_txt/cargo-owner.txt +++ b/man/generated_txt/cargo-owner.txt @@ -58,25 +58,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -94,15 +97,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. List owners of a package: diff --git a/man/generated_txt/cargo-package.txt b/man/generated_txt/cargo-package.txt index e0d52a4..061a4c0 100644 --- a/man/generated_txt/cargo-package.txt +++ b/man/generated_txt/cargo-package.txt @@ -1,169 +1,200 @@ CARGO-PACKAGE(1) -NAME - cargo-package - Assemble the local package into a distributable tarball +名称 + cargo-package - 将本地包打包为可分发的压缩文件 -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. + 此命令会在当前目录创建一个可分发的，压缩过的.crate文件并附带其源代码。文件会存储于 + target/package目录中。命令的执行可分为以下步骤： - 2. Create the compressed .crate file. - o The original Cargo.toml file is rewritten and normalized. + 1. 加载当前的工作空间以进行基本的检查。 + o + 如果不指定依赖的版本，就不能使用路径依赖。Cargo会在发布的包中忽略路径值。但 + dev-dependencies 没有这一限制。 - o [patch], [replace], and [workspace] sections are removed from the - manifest. + 2. 创建压缩的.crate文件 + o 原始的 Cargo.toml文件会被重写并规范化。 - 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 清单中的 [patch]、[replace]、[workspace]段会被移除。 - 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). + o + 如果包中有可执行的二进制或示例编译目标，则还会包含Cargo.lock文件。如果指定了 + --locked标志参数，cargo-install(1)会使用锁文件。 - 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. + o + 如果可用，会通过.cargo_vcs_info.json文件保存当前版本控制系统的签出哈希值(Checkout + Hash)。 + 可通过--allow-dirty标志参数指定不生成该文件。 - 4. Check that build scripts did not modify any source files. + 3. + 解压.crate文件并对其进行构建，以验证其确实可以成功构建。 + o + 这一步会从头开始构建，以确保可以从原始状态构建。可通过指定--no-verify标志参数来跳过这一步。 - The list of files included can be controlled with the include and - exclude fields in the manifest. + 4. 检查构建脚本是否会修改源代码的文件。 - See the reference - for more - details about packaging and publishing. + 包含文件的范围可通过清单中的include和exclude字段来控制。 -OPTIONS - Package Options + 更多关于打包和发布的细节可参见the reference + + + .cargo_vcs_info.json 的格式 + 会以下面的格式生成.cargo_vcs_info.json文件。 + + { + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" + } + + path_in_vcs会被设置为该软件包关于版本控制仓库的相对路径 + +可选参数 + 打包选项 -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. + 允许打包 在版本控制系统中仍有未提交内容 的包。 + + 选择包 + + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 + - Compilation Options + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 + + -p spec..., --package spec... + Package指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 + + --workspace + Package 工作区中的全体成员. + + --exclude SPEC... + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 + + 编译选项 --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. + 为指定架构执行 Package + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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 which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 - See the features documentation - - for more details. + 特性选择 + + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 - 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 + + 混杂选项 -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. + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 - 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -181,21 +212,20 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. -EXAMPLES - 1. Create a compressed .crate file of the current package: +示例 + 1. 为当前包创建一个压缩好的.crate文件: - cargo package + cargo package -SEE ALSO +相关 cargo(1), cargo-publish(1) diff --git a/man/generated_txt/cargo-pkgid.txt b/man/generated_txt/cargo-pkgid.txt index cee20fc..b79e011 100644 --- a/man/generated_txt/cargo-pkgid.txt +++ b/man/generated_txt/cargo-pkgid.txt @@ -47,57 +47,57 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -114,15 +114,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Retrieve package specification for foo package: diff --git a/man/generated_txt/cargo-publish.txt b/man/generated_txt/cargo-publish.txt index dc21409..ace2394 100644 --- a/man/generated_txt/cargo-publish.txt +++ b/man/generated_txt/cargo-publish.txt @@ -67,109 +67,113 @@ OPTIONS config key which defaults to crates-io. + Package Selection + By default, the package in the current working directory is selected. + The -p flag can be used to choose a different package in a workspace. + + -p spec, --package spec + The package to publish. See cargo-pkgid(1) for the SPEC format. + Compilation Options --target triple - Publish for the given architecture. The default is the host - architecture. The general format of the triple is - ---. Run rustc --print target-list for - a list of supported targets. + 为指定架构执行 Publish + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 - This may also be specified with the build.target config value - . + 也可通过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 + + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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 which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 - See the features documentation - - for more details. + 特性选择 + + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 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. + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -187,15 +191,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Publish the current package: diff --git a/man/generated_txt/cargo-report.txt b/man/generated_txt/cargo-report.txt new file mode 100644 index 0000000..489e45d --- /dev/null +++ b/man/generated_txt/cargo-report.txt @@ -0,0 +1,34 @@ +CARGO-REPORT(1) + +NAME + cargo-report - Generate and display various kinds of reports + +SYNOPSIS + cargo report type [options] + + DESCRIPTION + Displays a report of the given type - currently, only future-incompat is + supported + +OPTIONS + --id id + Show the report with the specified Cargo-generated id + + -p spec..., --package spec... + Only display a report for the specified package + +EXAMPLES + 1. Display the latest future-incompat report: + + cargo report future-incompat + + 2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +SEE ALSO + Future incompat report + + + cargo(1) + diff --git a/man/generated_txt/cargo-run.txt b/man/generated_txt/cargo-run.txt index a27d51f..4482ec6 100644 --- a/man/generated_txt/cargo-run.txt +++ b/man/generated_txt/cargo-run.txt @@ -34,76 +34,87 @@ OPTIONS --example name Run the specified example. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 - See the features documentation - - for more details. + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Run + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 - This may also be specified with the build.target config value - . + 也可通过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 + + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Run optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Run with the given profile. See the the reference + for more + details on profiles. + + --ignore-rust-version + Run the target even if the selected Rust compiler is older than the + required Rust version as configured in the project's rust-version + field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -136,34 +147,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -182,42 +190,18 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Build the local package and run its main target (assuming only one diff --git a/man/generated_txt/cargo-rustc.txt b/man/generated_txt/cargo-rustc.txt index 92a77d5..cfb735e 100644 --- a/man/generated_txt/cargo-rustc.txt +++ b/man/generated_txt/cargo-rustc.txt @@ -96,76 +96,104 @@ OPTIONS Build all targets. This is equivalent to specifying --lib --bins --tests --benches --examples. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 - See the features documentation - - for more details. + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Build + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Build optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Build with the given profile. + + The rustc subcommand will treat the following named profiles with + special behaviors: + + o check — Builds in the same way as the cargo-check(1) command + with the dev profile. + + o test — Builds in the same way as the cargo-test(1) command, + enabling building in test mode which will enable tests and enable + the test cfg option. See rustc tests + for more + detail. + + o bench — Builds in the same was as the cargo-bench(1) command, + similar to the test profile. + + See the the reference + for more + details on profiles. + + --ignore-rust-version + Build the target even if the selected Rust compiler is older than + the required Rust version as configured in the project's + rust-version field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -198,34 +226,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -244,42 +269,24 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Check if your package (not including dependencies) uses unsafe code: diff --git a/man/generated_txt/cargo-rustdoc.txt b/man/generated_txt/cargo-rustdoc.txt index 74c2815..ee5b4e7 100644 --- a/man/generated_txt/cargo-rustdoc.txt +++ b/man/generated_txt/cargo-rustdoc.txt @@ -34,7 +34,9 @@ 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. + environment variable or use the doc.browser + + configuration option. Package Selection By default, the package in the current working directory is selected. @@ -103,76 +105,87 @@ OPTIONS Document all targets. This is equivalent to specifying --lib --bins --tests --benches --examples. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 - See the features documentation - - for more details. + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Document + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 - This may also be specified with the build.target config value - . + 也可通过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 + + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Document optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Document with the given profile. See the the reference + for more + details on profiles. + + --ignore-rust-version + Document the target even if the selected Rust compiler is older than + the required Rust version as configured in the project's + rust-version field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -205,34 +218,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -251,42 +261,18 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Build documentation with custom CSS included from a given file: diff --git a/man/generated_txt/cargo-search.txt b/man/generated_txt/cargo-search.txt index 1f20b87..04e7852 100644 --- a/man/generated_txt/cargo-search.txt +++ b/man/generated_txt/cargo-search.txt @@ -28,25 +28,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -64,15 +67,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Search for a package from crates.io: diff --git a/man/generated_txt/cargo-test.txt b/man/generated_txt/cargo-test.txt index d7dde0e..526590d 100644 --- a/man/generated_txt/cargo-test.txt +++ b/man/generated_txt/cargo-test.txt @@ -14,7 +14,9 @@ DESCRIPTION (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. + arguments see the output of cargo test -- --help and check out the rustc + book's chapter on how tests work at + . As an example, this will filter for tests with foo in their name and run them on 3 threads in parallel: @@ -47,41 +49,33 @@ OPTIONS 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. + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 + + + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 -p spec..., --package spec... - Test only the specified packages. See cargo-pkgid(1) for the SPEC - format. This flag may be specified multiple times and supports - common Unix glob patterns like *, ? and []. However, to avoid your - shell accidentally expanding glob patterns before Cargo handles - them, you must use single quotes or double quotes around each - pattern. + Test指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 --workspace - Test all members in the workspace. + Test 工作区中的全体成员. --all - Deprecated alias for --workspace. + --workspace的已废弃的别名。 --exclude SPEC... - Exclude the specified packages. Must be used in conjunction with the - --workspace flag. This flag may be specified multiple times and - supports common Unix glob patterns like *, ? and []. However, to - avoid your shell accidentally expanding glob patterns before Cargo - handles them, you must use single quotes or double quotes around - each pattern. + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 Target Selection When no target selection options are given, cargo test will build the @@ -180,54 +174,62 @@ OPTIONS Test only the library's documentation. This cannot be mixed with other target options. - Feature Selection - The feature flags allow you to control which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 特性选择 + + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 - See the features documentation - - for more details. + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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. + 为指定架构执行 Test + 。默认情况下为本机的架构。三元组的格式为 + ---。执行 rustc --print target-list + 可得到支持的构建目标列表。 + + 也可通过build.target指定(config value + )。 - 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 + 注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 + 详情参见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. + -r, --release + Test optimized artifacts with the release profile. See also the + --profile option for choosing a specific profile by name. + + --profile name + Test with the given profile. See the the reference + for more + details on profiles. + + --ignore-rust-version + Test the target even if the selected Rust compiler is older than the + required Rust version as configured in the project's rust-version + field. 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. + + 用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR + 或 build.target-dir config value + 指定。 + + 默认情况下为根工作区中的target目录。 Display Options By default the Rust test harness hides output from test execution to @@ -237,25 +239,28 @@ OPTIONS 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . --message-format fmt @@ -288,34 +293,31 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -340,50 +342,24 @@ OPTIONS 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 + 要并行运行的作业数量。也可通过build.jobs config value + 指定。 + 默认为CPU数量。 + + --future-incompat-report + Displays a future-incompat report for any future-incompatible + warnings produced during execution of this command + + See cargo-report(1) + +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Execute all the unit and integration tests of the current package: diff --git a/man/generated_txt/cargo-tree.txt b/man/generated_txt/cargo-tree.txt index 7002a40..637e285 100644 --- a/man/generated_txt/cargo-tree.txt +++ b/man/generated_txt/cargo-tree.txt @@ -59,6 +59,13 @@ OPTIONS package's reverse dependencies only with the subtree of the package given to -p. + --prune spec + Prune the given package from the display of the dependency tree. + + --depth depth + Maximum display depth of the dependency tree. A depth of 1 displays + the direct dependencies, for example. + --no-dedupe Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not @@ -99,8 +106,10 @@ OPTIONS o no-dev — Do not include development dependencies. - The no- prefixed options cannot be mixed with the other dependency - kinds. + o no-proc-macro — Do not include procedural macro dependencies. + + The normal, build, dev, and all dependency kinds cannot be mixed + with no-normal, no-build, or no-dev dependency kinds. The default is normal,build,dev. @@ -129,6 +138,9 @@ OPTIONS o {f} — Comma-separated list of package features that are enabled. + o {lib} — The name, as used in a use statement, of the package's + library. + --prefix prefix Sets how each line is displayed. The prefix value can be one of: @@ -139,112 +151,102 @@ OPTIONS 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. + 选择包 + + 默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过--manifest-path给出清单文件路径， + 则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 + 单所定义的那个包。 - 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. + + 工作区的默认成员可通过清单中workspace.default-members项来显式指定。如果未指定，则其虚拟 + 工作区会包含全体工作区成员(等同于传递--workspace标志参数时)，而非虚拟工作区则仅包含根部箱自身。 -p spec..., --package spec... - Display only the specified packages. See cargo-pkgid(1) for the SPEC - format. This flag may be specified multiple times and supports - common Unix glob patterns like *, ? and []. However, to avoid your - shell accidentally expanding glob patterns before Cargo handles - them, you must use single quotes or double quotes around each - pattern. + Display指定包. SPEC的格式参见 cargo-pkgid(1) 。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 --workspace - Display all members in the workspace. + Display 工作区中的全体成员. --exclude SPEC... - Exclude the specified packages. Must be used in conjunction with the - --workspace flag. This flag may be specified multiple times and - supports common Unix glob patterns like *, ? and []. However, to - avoid your shell accidentally expanding glob patterns before Cargo - handles them, you must use single quotes or double quotes around - each pattern. + 排除指定包。必须与--workspace标志参数共同使用。 + 此标志参数可多次使用且支持Unix通配符(*, ? 和 + [])。不过，为避免shell可能错误地在Cargo获取到 + 之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 which features are enabled. When - no feature options are given, the default feature is activated for every - selected package. + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 - See the features documentation - - for more details. + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 + + 特性选择 + + 可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， + 则每个已选择的包都会自动使用default特性。 + + 详见the features documentation + 。 --features features - Space or comma separated list of features to activate. Features of - workspace members may be enabled with package-name/feature-name - syntax. This flag may be specified multiple times, which enables all - specified features. + + 传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 + 此参数可多次给定，以分别启用给定的特性。 --all-features - Activate all available features of all selected packages. + 为给定的包启用全部可用特性 --no-default-features - Do not activate the default feature of the selected packages. + 不启用给定包的default特性 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -262,15 +264,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Display the tree for the package in the current directory: diff --git a/man/generated_txt/cargo-uninstall.txt b/man/generated_txt/cargo-uninstall.txt index 6a13589..17791b3 100644 --- a/man/generated_txt/cargo-uninstall.txt +++ b/man/generated_txt/cargo-uninstall.txt @@ -40,25 +40,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -76,15 +79,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Uninstall a previously installed package. diff --git a/man/generated_txt/cargo-update.txt b/man/generated_txt/cargo-update.txt index b2232fd..cd35e81 100644 --- a/man/generated_txt/cargo-update.txt +++ b/man/generated_txt/cargo-update.txt @@ -47,57 +47,57 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -114,15 +114,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Update all dependencies in the lockfile: diff --git a/man/generated_txt/cargo-vendor.txt b/man/generated_txt/cargo-vendor.txt index 8bdc0ce..f1d7542 100644 --- a/man/generated_txt/cargo-vendor.txt +++ b/man/generated_txt/cargo-vendor.txt @@ -42,56 +42,56 @@ OPTIONS 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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -109,15 +109,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Vendor all dependencies into a local "vendor" folder diff --git a/man/generated_txt/cargo-verify-project.txt b/man/generated_txt/cargo-verify-project.txt index 7fe7237..f14f159 100644 --- a/man/generated_txt/cargo-verify-project.txt +++ b/man/generated_txt/cargo-verify-project.txt @@ -20,57 +20,57 @@ DESCRIPTION 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + + 用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。 --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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -87,10 +87,9 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. EXIT STATUS o 0: The workspace is OK. diff --git a/man/generated_txt/cargo-yank.txt b/man/generated_txt/cargo-yank.txt index 08dd675..2292b85 100644 --- a/man/generated_txt/cargo-yank.txt +++ b/man/generated_txt/cargo-yank.txt @@ -53,25 +53,28 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过term.color指定。 config value . Common Options @@ -89,15 +92,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. EXAMPLES 1. Yank a crate from the index: diff --git a/man/generated_txt/cargo.txt b/man/generated_txt/cargo.txt index 9476348..3aff9e4 100644 --- a/man/generated_txt/cargo.txt +++ b/man/generated_txt/cargo.txt @@ -130,53 +130,53 @@ 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 . + + 启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 + 依赖警告 以及 构建脚本输出 等额外的输出内容。 + 也可通过term.verbose指定。 config value + . -q, --quiet - No output printed to stdout. + 不输出Cargo的日志信息。也可通过term.quiet指定。 + config value + . --color when - Control when colored output is used. Valid values: + 控制输出内容的颜色。有效取值如下： - o auto (default): Automatically detect if color support is - available on the terminal. + o auto + (默认)：自动检测终端是否支持带颜色的输出。 - o always: Always display colors. + o always：总显示带颜色的输出。 - o never: Never display colors. + o never：从不显示带颜色的输出。 - May also be specified with the term.color config value + 也可通过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. + 这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo + 会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。 + + + 这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， + 或用于避免联网。 --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 - . + + 禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 + 并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 + + + 注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency + Resolution)结果。 + Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 + 所需依赖的方法，参见 cargo-fetch(1) 。 + + 也可以通过 net.offline config value + 指定。 Common Options +toolchain @@ -193,15 +193,14 @@ OPTIONS Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details. -ENVIRONMENT - See the reference +环境 + 关于Cargo所读取的环境变量，可参见the reference - for details on environment variables that Cargo reads. -EXIT STATUS - o 0: Cargo succeeded. +退出状态 + o 0: Cargo命令执行成功 - o 101: Cargo failed to complete. + o 101: Cargo命令未能完成. FILES ~/.cargo/ diff --git a/man/includes/options-display.md b/man/includes/options-display.md index b744de8..11f2990 100644 --- a/man/includes/options-display.md +++ b/man/includes/options-display.md @@ -1,22 +1,21 @@ {{#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` +启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过`term.verbose`指定。 [config value](../reference/config.html). {{/option}} {{#option "`-q`" "`--quiet`"}} -No output printed to stdout. +不输出Cargo的日志信息。也可通过`term.quiet`指定。 +[config value](../reference/config.html). {{/option}} {{#option "`--color` _when_"}} -Control when colored output is used. Valid values: +控制输出内容的颜色。有效取值如下： -- `auto` (default): Automatically detect if color support is available on the - terminal. -- `always`: Always display colors. -- `never`: Never display colors. +- `auto` (默认)：自动检测终端是否支持带颜色的输出。 +- `always`：总显示带颜色的输出。 +- `never`：从不显示带颜色的输出。 -May also be specified with the `term.color` +也可通过`term.color`指定。 [config value](../reference/config.html). {{/option}} diff --git a/man/includes/options-future-incompat.md b/man/includes/options-future-incompat.md new file mode 100644 index 0000000..3a8a1e7 --- /dev/null +++ b/man/includes/options-future-incompat.md @@ -0,0 +1,6 @@ +{{#option "`--future-incompat-report`"}} +Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command + +See {{man "cargo-report" 1}} +{{/option}} diff --git a/man/includes/options-ignore-rust-version.md b/man/includes/options-ignore-rust-version.md new file mode 100644 index 0000000..a151534 --- /dev/null +++ b/man/includes/options-ignore-rust-version.md @@ -0,0 +1,4 @@ +{{#option "`--ignore-rust-version`"}} +{{actionverb}} the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's `rust-version` field. +{{/option}} diff --git a/man/includes/options-jobs.md b/man/includes/options-jobs.md index 7dc00e3..d37c6ee 100644 --- a/man/includes/options-jobs.md +++ b/man/includes/options-jobs.md @@ -1,5 +1,4 @@ {{#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. +要并行运行的作业数量。也可通过`build.jobs` [config value](../reference/config.html)指定。 +默认为CPU数量。 {{/option}} diff --git a/man/includes/options-locked.md b/man/includes/options-locked.md index c9ac952..6e8c4cb 100644 --- a/man/includes/options-locked.md +++ b/man/includes/options-locked.md @@ -1,25 +1,18 @@ {{#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. +这两个选项用于保证`Cargo.lock`文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中`--frozen`选项会阻止Cargo访问网络以检查锁文件是否是最新的。 -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. +这些选项，可用于保证`Cargo.lock`文件是最新的(比如持续集成的构建过程)， +或用于避免联网。 {{/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. +禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。 -Beware that this may result in different dependency resolution than online -mode. Cargo will restrict itself to crates that are downloaded locally, even -if there might be a newer version as indicated in the local copy of the index. -See the {{man "cargo-fetch" 1}} command to download dependencies before going -offline. +注意，在此情况下可能会产生与联网状态下不同的依赖解析(__Dependency Resolution__)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 {{man "cargo-fetch" 1}} 。 -May also be specified with the `net.offline` [config value](../reference/config.html). +也可以通过 `net.offline` [config value](../reference/config.html)指定。 {{/option}} diff --git a/man/includes/options-manifest-path.md b/man/includes/options-manifest-path.md index b1d6eab..b009b0f 100644 --- a/man/includes/options-manifest-path.md +++ b/man/includes/options-manifest-path.md @@ -1,4 +1,3 @@ {{#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. +用于指定`Cargo.toml`文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找`Cargo.toml`文件。 {{/option}} diff --git a/man/includes/options-new.md b/man/includes/options-new.md index 30e2b34..e9792f0 100644 --- a/man/includes/options-new.md +++ b/man/includes/options-new.md @@ -10,7 +10,7 @@ Create a package with a library target (`src/lib.rs`). {{/option}} {{#option "`--edition` _edition_" }} -Specify the Rust edition to use. Default is 2018. +Specify the Rust edition to use. Default is 2021. Possible values: 2015, 2018, 2021 {{/option}} diff --git a/man/includes/options-profile-legacy-check.md b/man/includes/options-profile-legacy-check.md new file mode 100644 index 0000000..0ec82e6 --- /dev/null +++ b/man/includes/options-profile-legacy-check.md @@ -0,0 +1,10 @@ +{{#option "`--profile` _name_" }} +{{actionverb}} with the given profile. + +As a special case, specifying the `test` profile will also enable checking in +test mode which will enable checking tests and enable the `test` cfg option. +See [rustc tests](https://doc.rust-lang.org/rustc/tests/index.html) for more +detail. + +See the [the reference](../reference/profiles.html) for more details on profiles. +{{/option}} diff --git a/man/includes/options-profile.md b/man/includes/options-profile.md index 275bbef..2452e7b 100644 --- a/man/includes/options-profile.md +++ b/man/includes/options-profile.md @@ -1,7 +1,4 @@ {{#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. +{{actionverb}} with the given profile. +See the [the reference](../reference/profiles.html) for more details on profiles. {{/option}} diff --git a/man/includes/options-release.md b/man/includes/options-release.md index 4ee0fe6..723dbba 100644 --- a/man/includes/options-release.md +++ b/man/includes/options-release.md @@ -1,5 +1,4 @@ -{{#option "`--release`"}} -{{actionverb}} optimized artifacts with the `release` profile. See the -[PROFILES](#profiles) section for details on how this affects profile -selection. +{{#option "`-r`" "`--release`"}} +{{actionverb}} optimized artifacts with the `release` profile. +See also the `--profile` option for choosing a specific profile by name. {{/option}} diff --git a/man/includes/options-target-dir.md b/man/includes/options-target-dir.md index 3646e95..c842954 100644 --- a/man/includes/options-target-dir.md +++ b/man/includes/options-target-dir.md @@ -1,13 +1,10 @@ {{#option "`--target-dir` _directory_"}} -Directory for all generated artifacts and intermediate files. May also be -specified with the `CARGO_TARGET_DIR` environment variable, or the -`build.target-dir` [config value](../reference/config.html). -{{#if temp-target-dir}} Defaults to a new temporary folder located in the -temporary directory of the platform. +用于存放生成的工件以及中间文件的目录。也可通过环境变量`CARGO_TARGET_DIR` 或 +`build.target-dir` [config value](../reference/config.html)指定。 -When using `--path`, by default it will use `target` directory in the workspace -of the local crate unless `--target-dir` -is specified. -{{else}} Defaults to `target` in the root of the workspace. +{{#if temp-target-dir}} 默认情况下位于该平台临时目录下的一个新的临时文件夹。 + +当指定 `--path`标志参数时，若未指定`--target-dir`，则默认会使用工作区中的`target`目录。 +{{else}} 默认情况下为根工作区中的`target`目录。 {{/if}} {{/option}} diff --git a/man/includes/options-target-triple.md b/man/includes/options-target-triple.md index 6ad03c6..9999612 100644 --- a/man/includes/options-target-triple.md +++ b/man/includes/options-target-triple.md @@ -1,13 +1,10 @@ {{#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. +为指定架构执行 {{actionverb}} 。默认情况下为本机的架构。三元组的格式为 +`---`。执行 `rustc --print target-list` +可得到支持的构建目标列表。 -This may also be specified with the `build.target` -[config value](../reference/config.html). +也可通过`build.target`指定([config value](../reference/config.html))。 -Note that specifying this flag makes Cargo run in a different mode where the -target artifacts are placed in a separate directory. See the -[build cache](../guide/build-cache.html) documentation for more details. +注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见[build cache](../guide/build-cache.html) {{/option}} diff --git a/man/includes/section-environment.md b/man/includes/section-environment.md index aae5f07..d1afafc 100644 --- a/man/includes/section-environment.md +++ b/man/includes/section-environment.md @@ -1,4 +1,3 @@ -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) diff --git a/man/includes/section-exit-status.md b/man/includes/section-exit-status.md index a812336..53ea7be 100644 --- a/man/includes/section-exit-status.md +++ b/man/includes/section-exit-status.md @@ -1,4 +1,4 @@ -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. diff --git a/man/includes/section-features.md b/man/includes/section-features.md index f4947f7..67093ba 100644 --- a/man/includes/section-features.md +++ b/man/includes/section-features.md @@ -1,26 +1,23 @@ -### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。 {{#options}} {{#option "`--features` _features_" }} -Space or comma separated list of features to activate. Features of workspace -members may be enabled with `package-name/feature-name` syntax. This flag may -be specified multiple times, which enables all specified features. +传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过`包名/特性名`的语法启用。 +此参数可多次给定，以分别启用给定的特性。 {{/option}} {{#option "`--all-features`" }} -Activate all available features of all selected packages. +为给定的包启用全部可用特性 {{/option}} {{#option "`--no-default-features`" }} -Do not activate the `default` feature of the selected packages. +不启用给定包的`default`特性 {{/option}} {{/options}} diff --git a/man/includes/section-package-selection.md b/man/includes/section-package-selection.md index 8d7d621..5977004 100644 --- a/man/includes/section-package-selection.md +++ b/man/includes/section-package-selection.md @@ -1,42 +1,34 @@ -### 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. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。 {{#options}} {{#option "`-p` _spec_..." "`--package` _spec_..."}} -{{actionverb}} only the specified packages. See {{man "cargo-pkgid" 1}} for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like `*`, `?` and `[]`. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern. +{{actionverb}}指定包. SPEC的格式参见 {{man "cargo-pkgid" 1}} 。 +此标志参数可多次使用且支持Unix通配符(`*`, `?` 和 `[]`)。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 {{/option}} {{#option "`--workspace`" }} -{{actionverb}} all members in the workspace. +{{actionverb}} 工作区中的全体成员. {{/option}} {{#unless noall}} {{#option "`--all`" }} -Deprecated alias for `--workspace`. +`--workspace`的已废弃的别名。 {{/option}} {{/unless}} {{#option "`--exclude` _SPEC_..." }} -Exclude the specified packages. Must be used in conjunction with the -`--workspace` flag. This flag may be specified multiple times and supports -common Unix glob patterns like `*`, `?` and `[]`. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern. +排除指定包。必须与`--workspace`标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(`*`, `?` 和 `[]`)。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。 {{/option}} {{/options}} diff --git a/man/includes/section-profiles.md b/man/includes/section-profiles.md deleted file mode 100644 index d0a4072..0000000 --- a/man/includes/section-profiles.md +++ /dev/null @@ -1,16 +0,0 @@ -## 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. diff --git a/mdman/Cargo.lock b/mdman/Cargo.lock new file mode 100644 index 0000000..50948b5 --- /dev/null +++ b/mdman/Cargo.lock @@ -0,0 +1,460 @@ +# 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 = "form_urlencoded" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5fc25a87fa4fd2094bffb06925852034d90a17f0d1e05197d4956d3555752191" +dependencies = [ + "matches", + "percent-encoding", +] + +[[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.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a507c383b2d33b5fc35d1861e77e6b383d158b2da5e14fe51b83dfedf6fd578c" +dependencies = [ + "form_urlencoded", + "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/mdman/Cargo.toml b/mdman/Cargo.toml new file mode 100644 index 0000000..bae299f --- /dev/null +++ b/mdman/Cargo.toml @@ -0,0 +1,17 @@ +[package] +name = "mdman" +version = "0.1.0" +edition = "2021" +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.2.2" + +[dev-dependencies] +pretty_assertions = "0.6.1" diff --git a/mdman/README.md b/mdman/README.md new file mode 100644 index 0000000..e28b596 --- /dev/null +++ b/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/mdman/build-man.sh b/mdman/build-man.sh new file mode 100644 index 0000000..9286b17 --- /dev/null +++ b/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/mdman/doc/mdman.md b/mdman/doc/mdman.md new file mode 100644 index 0000000..2025c13 --- /dev/null +++ b/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/mdman/doc/out/mdman.1 b/mdman/doc/out/mdman.1 new file mode 100644 index 0000000..0718d6d --- /dev/null +++ b/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/mdman/doc/out/mdman.md b/mdman/doc/out/mdman.md new file mode 100644 index 0000000..d0dd345 --- /dev/null +++ b/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/mdman/doc/out/mdman.txt b/mdman/doc/out/mdman.txt new file mode 100644 index 0000000..83fa7de --- /dev/null +++ b/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/mdman/src/format.rs b/mdman/src/format.rs new file mode 100644 index 0000000..7bc9781 --- /dev/null +++ b/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/mdman/src/format/man.rs b/mdman/src/format/man.rs new file mode 100644 index 0000000..ecad77e --- /dev/null +++ b/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/mdman/src/format/md.rs b/mdman/src/format/md.rs new file mode 100644 index 0000000..0e1c498 --- /dev/null +++ b/mdman/src/format/md.rs @@ -0,0 +1,112 @@ +//! Markdown formatter. + +use crate::util::unwrap; +use crate::ManMap; +use anyhow::{bail, format_err, Error}; +use std::fmt::Write; + +pub struct MdFormatter { + man_map: ManMap, +} + +impl MdFormatter { + pub fn new(man_map: ManMap) -> MdFormatter { + MdFormatter { man_map } + } +} + +impl MdFormatter { + fn render_html(&self, input: &str) -> Result { + let parser = crate::md_parser(input, None); + 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.replace("\r\n", "\n")) + } + + 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!("[{}({})]({}.html)", 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/mdman/src/format/text.rs b/mdman/src/format/text.rs new file mode 100644 index 0000000..2c6a4ff --- /dev/null +++ b/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/mdman/src/hbs.rs b/mdman/src/hbs.rs new file mode 100644 index 0000000..a8cbae9 --- /dev/null +++ b/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/mdman/src/lib.rs b/mdman/src/lib.rs new file mode 100644 index 0000000..0b17be5 --- /dev/null +++ b/mdman/src/lib.rs @@ -0,0 +1,121 @@ +//! 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(man_map)), + 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) +} + +/// 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) + }); + String::from(joined).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/mdman/src/main.rs b/mdman/src/main.rs new file mode 100644 index 0000000..2bdf96d --- /dev/null +++ b/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/mdman/src/util.rs b/mdman/src/util.rs new file mode 100644 index 0000000..e85f220 --- /dev/null +++ b/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/mdman/tests/compare.rs b/mdman/tests/compare.rs new file mode 100644 index 0000000..3e679d1 --- /dev/null +++ b/mdman/tests/compare.rs @@ -0,0 +1,48 @@ +//! 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(); + // Fix if Windows checked out with autocrlf. + let expected = expected.replace("\r\n", "\n"); + 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/mdman/tests/compare/expected/formatting.1 b/mdman/tests/compare/expected/formatting.1 new file mode 100644 index 0000000..dbd2452 --- /dev/null +++ b/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/mdman/tests/compare/expected/formatting.md b/mdman/tests/compare/expected/formatting.md new file mode 100644 index 0000000..6909bd4 --- /dev/null +++ b/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/mdman/tests/compare/expected/formatting.txt b/mdman/tests/compare/expected/formatting.txt new file mode 100644 index 0000000..865b714 --- /dev/null +++ b/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/mdman/tests/compare/expected/links.1 b/mdman/tests/compare/expected/links.1 new file mode 100644 index 0000000..e56cef7 --- /dev/null +++ b/mdman/tests/compare/expected/links.1 @@ -0,0 +1,45 @@ +'\" 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) +.sp +\fISome link\fR +.sp +\fB\-\-include\fR +.RS 4 +Testing an \fIincluded link\fR \&. +.RE +.SH "OPTIONS" +.sp +\fB\-\-foo\-bar\fR +.RS 4 +Example \fIlink\fR \&. +See \fBother\-cmd\fR(1), \fBlocal\-cmd\fR(1) +.RE diff --git a/mdman/tests/compare/expected/links.md b/mdman/tests/compare/expected/links.md new file mode 100644 index 0000000..11afcf3 --- /dev/null +++ b/mdman/tests/compare/expected/links.md @@ -0,0 +1,56 @@ +# 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.html) + +[Some link](foo.html) + +
+
--include
+
Testing an included link.
+ +
+ + +## OPTIONS + +
+ +
--foo-bar
+
Example link. +See other-cmd(1), local-cmd(1)
+ + +
+ + +[bar]: https://example.com/bar +[collapsed]: https://example.com/collapsed +[shortcut]: https://example.com/shortcut diff --git a/mdman/tests/compare/expected/links.txt b/mdman/tests/compare/expected/links.txt new file mode 100644 index 0000000..7748c3d --- /dev/null +++ b/mdman/tests/compare/expected/links.txt @@ -0,0 +1,40 @@ +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) + + Some link + + --include + Testing an included link . + +OPTIONS + --foo-bar + Example link . See other-cmd(1), + local-cmd(1) + diff --git a/mdman/tests/compare/expected/options.1 b/mdman/tests/compare/expected/options.1 new file mode 100644 index 0000000..2d75cd2 --- /dev/null +++ b/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/mdman/tests/compare/expected/options.md b/mdman/tests/compare/expected/options.md new file mode 100644 index 0000000..d8b8276 --- /dev/null +++ b/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.html) [abc(7)](abc.html) diff --git a/mdman/tests/compare/expected/options.txt b/mdman/tests/compare/expected/options.txt new file mode 100644 index 0000000..32ccfd2 --- /dev/null +++ b/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/mdman/tests/compare/expected/tables.1 b/mdman/tests/compare/expected/tables.1 new file mode 100644 index 0000000..7175a3e --- /dev/null +++ b/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/mdman/tests/compare/expected/tables.md b/mdman/tests/compare/expected/tables.md new file mode 100644 index 0000000..831132c --- /dev/null +++ b/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/mdman/tests/compare/expected/tables.txt b/mdman/tests/compare/expected/tables.txt new file mode 100644 index 0000000..fed53f9 --- /dev/null +++ b/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/mdman/tests/compare/expected/vars.7 b/mdman/tests/compare/expected/vars.7 new file mode 100644 index 0000000..0ee33ad --- /dev/null +++ b/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/mdman/tests/compare/expected/vars.md b/mdman/tests/compare/expected/vars.md new file mode 100644 index 0000000..2493aca --- /dev/null +++ b/mdman/tests/compare/expected/vars.md @@ -0,0 +1,7 @@ +# vars(7) + + + +Bar + +bar diff --git a/mdman/tests/compare/expected/vars.txt b/mdman/tests/compare/expected/vars.txt new file mode 100644 index 0000000..11d34ca --- /dev/null +++ b/mdman/tests/compare/expected/vars.txt @@ -0,0 +1,6 @@ +VARS(7) + +Bar + +bar + diff --git a/mdman/tests/compare/formatting.md b/mdman/tests/compare/formatting.md new file mode 100644 index 0000000..6909bd4 --- /dev/null +++ b/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/mdman/tests/compare/includes/links-include.md b/mdman/tests/compare/includes/links-include.md new file mode 100644 index 0000000..7373360 --- /dev/null +++ b/mdman/tests/compare/includes/links-include.md @@ -0,0 +1,7 @@ +[Some link](foo.html) + +{{#options}} +{{#option "`--include`"}} +Testing an [included link](included_link.html). +{{/option}} +{{/options}} diff --git a/mdman/tests/compare/includes/options-common.md b/mdman/tests/compare/includes/options-common.md new file mode 100644 index 0000000..07404e3 --- /dev/null +++ b/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/mdman/tests/compare/links.md b/mdman/tests/compare/links.md new file mode 100644 index 0000000..949f374 --- /dev/null +++ b/mdman/tests/compare/links.md @@ -0,0 +1,49 @@ +# 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}} + +{{> links-include}} + +## OPTIONS + +{{#options}} + +{{#option "`--foo-bar`"}} +Example [link](bar.html). +See {{man "other-cmd" 1}}, {{man "local-cmd" 1}} +{{/option}} + +{{/options}} + + +[bar]: https://example.com/bar +[collapsed]: https://example.com/collapsed +[shortcut]: https://example.com/shortcut diff --git a/mdman/tests/compare/options.md b/mdman/tests/compare/options.md new file mode 100644 index 0000000..51415b0 --- /dev/null +++ b/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/mdman/tests/compare/tables.md b/mdman/tests/compare/tables.md new file mode 100644 index 0000000..831132c --- /dev/null +++ b/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/mdman/tests/compare/vars.md b/mdman/tests/compare/vars.md new file mode 100644 index 0000000..d41b765 --- /dev/null +++ b/mdman/tests/compare/vars.md @@ -0,0 +1,7 @@ +# vars(7) + +{{*set foo="Bar"}} + +{{foo}} + +{{lower foo}} diff --git a/mdman/tests/invalid.rs b/mdman/tests/invalid.rs new file mode 100644 index 0000000..cc81d06 --- /dev/null +++ b/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/mdman/tests/invalid/nested.md b/mdman/tests/invalid/nested.md new file mode 100644 index 0000000..6a33e6d --- /dev/null +++ b/mdman/tests/invalid/nested.md @@ -0,0 +1,6 @@ +# nested(1) + +{{#options}} +{{#options}} +{{/options}} +{{/options}} diff --git a/mdman/tests/invalid/not-inside-options.md b/mdman/tests/invalid/not-inside-options.md new file mode 100644 index 0000000..b6c816f --- /dev/null +++ b/mdman/tests/invalid/not-inside-options.md @@ -0,0 +1,5 @@ +# not-inside-options(1) + +{{#option "`-o`"}} +Testing without options block. +{{/option}} diff --git a/src/commands/cargo-bench.md b/src/commands/cargo-bench.md index 74b3d49..4648ab5 100644 --- a/src/commands/cargo-bench.md +++ b/src/commands/cargo-bench.md @@ -19,9 +19,12 @@ 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`): +arguments see the output of `cargo bench -- --help` and check out the rustc +book's chapter on how tests work at +. + +As an example, this will run only the benchmark named `foo` (and skip other +similarly named benchmarks like `foobar`): cargo bench -- foo --exact @@ -43,6 +46,14 @@ function to handle running benchmarks. > running benchmarks on the stable channel, such as > [Criterion](https://crates.io/crates/criterion). +By default, `cargo bench` uses the [`bench` profile], which enables +optimizations and disables debugging information. If you need to debug a +benchmark, you can use the `--profile=dev` command-line option to switch to +the dev profile. You can then run the debug-enabled benchmark within a +debugger. + +[`bench` profile]: ../reference/profiles.html#bench + ## OPTIONS ### Benchmark Options @@ -63,46 +74,38 @@ 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. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。
-p spec...
--package spec...
-
Benchmark only the specified packages. See cargo-pkgid(1) for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like *, ? and []. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern.
+
Benchmark指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
--workspace
-
Benchmark all members in the workspace.
+
Benchmark 工作区中的全体成员.
--all
-
Deprecated alias for --workspace.
+
--workspace的已废弃的别名。
--exclude SPEC...
-
Exclude the specified packages. Must be used in conjunction with the ---workspace flag. This flag may be specified multiple times and supports -common Unix glob patterns like *, ? and []. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern.
+
排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
@@ -197,29 +200,26 @@ manifest settings for the target. -### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -230,15 +230,24 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Benchmark 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+ + + +
--profile name
+
Benchmark with the given profile. +See the the reference for more details on profiles.
+ + + +
--ignore-rust-version
+
Benchmark the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -248,10 +257,9 @@ target artifacts are placed in a separate directory. See the
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -268,26 +276,25 @@ passing `--nocapture` to the benchmark binaries:
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -322,33 +329,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -386,40 +385,21 @@ 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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-## 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.html) 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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-build.md b/src/commands/cargo-build.md index 8efbd73..4817483 100644 --- a/src/commands/cargo-build.md +++ b/src/commands/cargo-build.md @@ -15,46 +15,38 @@ 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. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。
-p spec...
--package spec...
-
Build only the specified packages. See cargo-pkgid(1) for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like *, ? and []. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern.
+
Build指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
--workspace
-
Build all members in the workspace.
+
Build 工作区中的全体成员.
--all
-
Deprecated alias for --workspace.
+
--workspace的已废弃的别名。
--exclude SPEC...
-
Exclude the specified packages. Must be used in conjunction with the ---workspace flag. This flag may be specified multiple times and supports -common Unix glob patterns like *, ? and []. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern.
+
排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
@@ -136,29 +128,26 @@ manifest settings for the target.
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -169,22 +158,31 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Build 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Build optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Build optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
+ + + +
--profile name
+
Build with the given profile. +See the the reference for more details on profiles.
+ + + +
--ignore-rust-version
+
Build the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -194,10 +192,9 @@ selection.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -216,26 +213,25 @@ See https://github.com/
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -278,33 +274,25 @@ See https://github.com/
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -338,41 +326,27 @@ for more information about how toolchain overrides work.
-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-
- -## 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. +
--future-incompat-report
+
Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command

+

See cargo-report(1)

-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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-check.md b/src/commands/cargo-check.md index 421e567..ae48a8e 100644 --- a/src/commands/cargo-check.md +++ b/src/commands/cargo-check.md @@ -20,46 +20,38 @@ generation, so they inherently won't be reported with `cargo check`. ## OPTIONS -### Package Selection +### 选择包 -By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if -`--manifest-path` is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。
-p spec...
--package spec...
-
Check only the specified packages. See cargo-pkgid(1) for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like *, ? and []. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern.
+
Check指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
--workspace
-
Check all members in the workspace.
+
Check 工作区中的全体成员.
--all
-
Deprecated alias for --workspace.
+
--workspace的已废弃的别名。
--exclude SPEC...
-
Exclude the specified packages. Must be used in conjunction with the ---workspace flag. This flag may be specified multiple times and supports -common Unix glob patterns like *, ? and []. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern.
+
排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
@@ -141,29 +133,26 @@ manifest settings for the target.
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -174,31 +163,35 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Check 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Check optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Check optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
--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.
+
Check with the given profile.

+

As a special case, specifying the test profile will also enable checking in +test mode which will enable checking tests and enable the test cfg option. +See rustc tests for more +detail.

+

See the the reference for more details on profiles.

+ + + +
--ignore-rust-version
+
Check the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -208,10 +201,9 @@ used.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -221,26 +213,25 @@ Defaults to target in the root of the workspace.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -274,33 +265,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -334,41 +317,27 @@ for more information about how toolchain overrides work.
-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.
- +
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-
- -## 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. +
--future-incompat-report
+
Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command

+

See cargo-report(1)

-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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-clean.md b/src/commands/cargo-clean.md index 33d6dc0..9f89cb1 100644 --- a/src/commands/cargo-clean.md +++ b/src/commands/cargo-clean.md @@ -1,133 +1,120 @@ # cargo-clean(1) -## NAME +## 名称 -cargo-clean - Remove generated artifacts +cargo-clean - 移除已生成的工件 -## SYNOPSIS +## 用法 `cargo clean` [_options_] -## DESCRIPTION +## 描述 -Remove artifacts from the target directory that Cargo has generated in the -past. +将Cargo生成的工件从生成目标目录中移除。 -With no options, `cargo clean` will delete the entire target directory. +若不添加参数，`cargo clean` 会删除整个target目录。 -## 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.
+
只清理参数指定的包中的文件。这个参数可以多次使用来指定多个包，详见 cargo-pkgid(1) 。
-### Clean Options +### 清理选项
--doc
-
This option will cause cargo clean to remove only the doc directory in -the target directory.
+
添加该参数后，cargo clean命令只会移除生成目标目录中的doc目录。
--release
-
Clean all artifacts that were built with the release or bench profiles.
+
移除release目录中的工件。
+ + +
--profile name
+
移除指定编译配置(Profile)目录中的全部工件。
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

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

+
为指定架构执行 Clean 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

-### 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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -156,27 +143,26 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. -## EXAMPLES +## 示例 -1. Remove the entire target directory: +1. 移除整个生成目标目录: cargo clean -2. Remove only the release artifacts: +2. 仅移除release目录中的工件: cargo clean --release -## SEE ALSO +## 相关 [cargo(1)](cargo.html), [cargo-build(1)](cargo-build.html) diff --git a/src/commands/cargo-doc.md b/src/commands/cargo-doc.md index 7640416..daa3db0 100644 --- a/src/commands/cargo-doc.md +++ b/src/commands/cargo-doc.md @@ -22,7 +22,9 @@ is placed in `target/doc` in rustdoc's usual format.
--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.
+browser unless you define another one in the BROWSER environment variable +or use the doc.browser configuration +option.
--no-deps
@@ -30,51 +32,43 @@ browser unless you define another one in the BROWSER environment va
--document-private-items
-
Include non-public items in the documentation.
+
Include non-public items in the documentation. This will be enabled by default if documenting a binary target.
-### Package Selection +### 选择包 -By default, when no package selection options are given, the packages selected -depend on the selected manifest file (based on the current working directory if -`--manifest-path` is not given). If the manifest is the root of a workspace then -the workspaces default members are selected, otherwise only the package defined -by the manifest will be selected. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。
-p spec...
--package spec...
-
Document only the specified packages. See cargo-pkgid(1) for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like *, ? and []. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern.
+
Document指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
--workspace
-
Document all members in the workspace.
+
Document 工作区中的全体成员.
--all
-
Deprecated alias for --workspace.
+
--workspace的已废弃的别名。
--exclude SPEC...
-
Exclude the specified packages. Must be used in conjunction with the ---workspace flag. This flag may be specified multiple times and supports -common Unix glob patterns like *, ? and []. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern.
+
排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
@@ -105,31 +99,38 @@ and supports common Unix glob patterns.
Document all binary targets.
+ +
--example name...
+
Document the specified example. This flag may be specified multiple times +and supports common Unix glob patterns.
+ + +
--examples
+
Document all example targets.
+ + -### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -140,22 +141,31 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Document 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Document optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Document optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
+ + + +
--profile name
+
Document with the given profile. +See the the reference for more details on profiles.
+ + + +
--ignore-rust-version
+
Document the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -165,10 +175,9 @@ selection.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -178,26 +187,25 @@ Defaults to target in the root of the workspace.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -231,33 +239,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -291,41 +291,21 @@ for more information about how toolchain overrides work.
-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-## 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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-fetch.md b/src/commands/cargo-fetch.md index 1a7a17d..9128663 100644 --- a/src/commands/cargo-fetch.md +++ b/src/commands/cargo-fetch.md @@ -31,15 +31,12 @@ you plan to use Cargo without a network with the `--offline` flag.
--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.

+
为指定架构执行 Fetch 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

@@ -49,26 +46,25 @@ target artifacts are placed in a separate directory. See the
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -78,33 +74,25 @@ terminal.
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -133,16 +121,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-fix.md b/src/commands/cargo-fix.md index 0d8c914..d563575 100644 --- a/src/commands/cargo-fix.md +++ b/src/commands/cargo-fix.md @@ -100,46 +100,38 @@ edition.
-### 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. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。
-p spec...
--package spec...
-
Fix only the specified packages. See cargo-pkgid(1) for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like *, ? and []. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern.
+
Fix指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
--workspace
-
Fix all members in the workspace.
+
Fix 工作区中的全体成员.
--all
-
Deprecated alias for --workspace.
+
--workspace的已废弃的别名。
--exclude SPEC...
-
Exclude the specified packages. Must be used in conjunction with the ---workspace flag. This flag may be specified multiple times and supports -common Unix glob patterns like *, ? and []. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern.
+
排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
@@ -221,29 +213,26 @@ manifest settings for the target.
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -254,31 +243,35 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Fix 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Fix optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Fix optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
--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.
+
Fix with the given profile.

+

As a special case, specifying the test profile will also enable checking in +test mode which will enable checking tests and enable the test cfg option. +See rustc tests for more +detail.

+

See the the reference for more details on profiles.

+ + + +
--ignore-rust-version
+
Fix the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -288,10 +281,9 @@ used.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -301,26 +293,25 @@ Defaults to target in the root of the workspace.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -354,33 +345,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -414,41 +397,21 @@ for more information about how toolchain overrides work.
-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-## 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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-generate-lockfile.md b/src/commands/cargo-generate-lockfile.md index e41ea9e..b861569 100644 --- a/src/commands/cargo-generate-lockfile.md +++ b/src/commands/cargo-generate-lockfile.md @@ -24,26 +24,25 @@ lockfile and has more options for controlling update behavior.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -53,33 +52,25 @@ terminal.
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -108,16 +99,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-init.md b/src/commands/cargo-init.md index 4e5dc50..d23319d 100644 --- a/src/commands/cargo-init.md +++ b/src/commands/cargo-init.md @@ -39,7 +39,7 @@ This is the default behavior.
--edition edition
-
Specify the Rust edition to use. Default is 2018. +
Specify the Rust edition to use. Default is 2021. Possible values: 2015, 2018, 2021
@@ -72,26 +72,25 @@ be restricted.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -121,16 +120,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-install.md b/src/commands/cargo-install.md index 1639b28..98a2990 100644 --- a/src/commands/cargo-install.md +++ b/src/commands/cargo-install.md @@ -49,7 +49,7 @@ 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 profile (`--profile`). - The target (`--target`). Installing with `--path` will always build and install, unless there are @@ -168,29 +168,26 @@ which is defined by the registry.default config key which defaults
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -201,32 +198,32 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Install 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

--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 a new temporary folder located in the -temporary directory of the platform.

-

When using --path, by default it will use target directory in the workspace -of the local crate unless --target-dir -is specified.

+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下位于该平台临时目录下的一个新的临时文件夹。

+

当指定 --path标志参数时，若未指定--target-dir，则默认会使用工作区中的target目录。

--debug
-
Build with the dev profile instead the release profile.
+
Build with the dev profile instead the release profile. +See also the --profile option for choosing a specific profile by name.
+ + +
--profile name
+
Install with the given profile. +See the the reference for more details on profiles.
+
@@ -236,26 +233,19 @@ is specified.
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -265,9 +255,8 @@ offline.

-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
@@ -277,29 +266,53 @@ the number of CPUs.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过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. Conflicts with +short and json.
    • +
  • short: Emit shorter, human-readable text messages. Conflicts with human +and json.
    • +
  • json: Emit JSON messages to stdout. See +the reference +for more details. Conflicts with human and short.
    • +
  • json-diagnostic-short: Ensure the rendered field of JSON messages contains +the "short" rendering from rustc. Cannot be used with human or short.
    • +
  • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON messages +contains embedded ANSI color codes for respecting rustc's default color +scheme. Cannot be used with human or short.
    • +
  • json-render-diagnostics: Instruct Cargo to not include rustc diagnostics in +in JSON messages printed, but instead Cargo itself should render the +JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others +coming from rustc are still emitted. Cannot be used with human or short.
    • +
+ + +
### Common Options @@ -326,16 +339,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-locate-project.md b/src/commands/cargo-locate-project.md index 123dc13..cfcfd46 100644 --- a/src/commands/cargo-locate-project.md +++ b/src/commands/cargo-locate-project.md @@ -38,26 +38,25 @@ workspace member.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -67,8 +66,7 @@ terminal.
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
@@ -97,16 +95,15 @@ for more information about how toolchain overrides work. -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-login.md b/src/commands/cargo-login.md index 23ee8f3..c444bb1 100644 --- a/src/commands/cargo-login.md +++ b/src/commands/cargo-login.md @@ -40,26 +40,25 @@ which is defined by the registry.default config key which defaults
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -89,16 +88,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-metadata.md b/src/commands/cargo-metadata.md index b59e263..5a4f5fe 100644 --- a/src/commands/cargo-metadata.md +++ b/src/commands/cargo-metadata.md @@ -180,6 +180,10 @@ The output has the following format: "categories": [ "command-line-utilities" ], + /* Optional string that is the default binary picked by cargo run. */ + "default_run": null, + /* Optional string that is the minimum supported rust version */ + "rust_version": "1.56", /* Array of keywords from the manifest. */ "keywords": [ "cli" @@ -315,29 +319,26 @@ reproduction of the information within Cargo.toml. -### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -348,26 +349,25 @@ be specified multiple times, which enables all specified features.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -377,33 +377,25 @@ terminal.
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -432,16 +424,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-new.md b/src/commands/cargo-new.md index 8236a08..001fb81 100644 --- a/src/commands/cargo-new.md +++ b/src/commands/cargo-new.md @@ -34,7 +34,7 @@ This is the default behavior.
--edition edition
-
Specify the Rust edition to use. Default is 2018. +
Specify the Rust edition to use. Default is 2021. Possible values: 2015, 2018, 2021
@@ -67,26 +67,25 @@ be restricted.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -116,16 +115,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-owner.md b/src/commands/cargo-owner.md index 7ed275c..0fd957f 100644 --- a/src/commands/cargo-owner.md +++ b/src/commands/cargo-owner.md @@ -78,26 +78,25 @@ which is defined by the registry.default config key which defaults
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -127,16 +126,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-package.md b/src/commands/cargo-package.md index e0935bd..aa18c42 100644 --- a/src/commands/cargo-package.md +++ b/src/commands/cargo-package.md @@ -1,202 +1,223 @@ # cargo-package(1) -## NAME -cargo-package - Assemble the local package into a distributable tarball +## 名称 -## SYNOPSIS +cargo-package - 将本地包打包为可分发的压缩文件 + +## 用法 `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.html) 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 +## 描述 + +此命令会在当前目录创建一个可分发的，压缩过的`.crate`文件并附带其源代码。文件会存储于 +`target/package`目录中。命令的执行可分为以下步骤： + +1. 加载当前的工作空间以进行基本的检查。 + - 如果不指定依赖的版本，就不能使用路径依赖。Cargo会在发布的包中忽略路径值。但 + `dev-dependencies` 没有这一限制。 +2. 创建压缩的`.crate`文件 + - 原始的 `Cargo.toml`文件会被重写并规范化。 + - 清单中的 `[patch]`、`[replace]`、`[workspace]`段会被移除。 + - 如果包中有可执行的二进制或示例编译目标，则还会包含`Cargo.lock`文件。如果指定了 + `--locked`标志参数，[cargo-install(1)](cargo-install.html)会使用锁文件。 + - 如果可用，会通过`.cargo_vcs_info.json`文件保存当前版本控制系统的签出哈希值(__Checkout Hash__)。 + 可通过`--allow-dirty`标志参数指定不生成该文件。 +3. 解压`.crate`文件并对其进行构建，以验证其确实可以成功构建。 + - 这一步会从头开始构建，以确保可以从原始状态构建。可通过指定`--no-verify`标志参数来跳过这一步。 +4. 检查构建脚本是否会修改源代码的文件。 + +包含文件的范围可通过清单中的`include`和`exclude`字段来控制。 + +更多关于打包和发布的细节可参见[the reference](../reference/publishing.html) + +### .cargo_vcs_info.json 的格式 + +会以下面的格式生成`.cargo_vcs_info.json`文件。 + +```javascript +{ + "git": { + "sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302" + }, + "path_in_vcs": "" +} +``` + +`path_in_vcs`会被设置为该软件包关于版本控制仓库的相对路径 + +## 可选参数 + +### 打包选项
-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.
+
允许打包 在版本控制系统中仍有未提交内容 的包。
+ + +
+ +### 选择包 + +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 + +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。 + +
+ +
-p spec...
+
--package spec...
+
Package指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
+ + +
--workspace
+
Package 工作区中的全体成员.
+ + + + +
--exclude SPEC...
+
排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
-### 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.

+
为指定架构执行 Package 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
-### 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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-### 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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -226,23 +247,22 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. -## EXAMPLES +## 示例 -1. Create a compressed `.crate` file of the current package: +1. 为当前包创建一个压缩好的`.crate`文件: - cargo package + cargo package -## SEE ALSO +## 相关 [cargo(1)](cargo.html), [cargo-publish(1)](cargo-publish.html) diff --git a/src/commands/cargo-pkgid.md b/src/commands/cargo-pkgid.md index c380738..27f16ef 100644 --- a/src/commands/cargo-pkgid.md +++ b/src/commands/cargo-pkgid.md @@ -51,26 +51,25 @@ _url_`#`_name_`:`_version_ | `https://github.com/rust-lang/cargo#crates-io:0.21.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -81,33 +80,25 @@ terminal.
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -137,16 +128,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-publish.md b/src/commands/cargo-publish.md index 511688c..9937b30 100644 --- a/src/commands/cargo-publish.md +++ b/src/commands/cargo-publish.md @@ -76,56 +76,65 @@ which defaults to crates-io.
+### Package Selection + +By default, the package in the current working directory is selected. The `-p` +flag can be used to choose a different package in a workspace. + +
+ +
-p spec
+
--package spec
+
The package to publish. See cargo-pkgid(1) for the SPEC +format.
+ + +
+ + ### Compilation Options
--target triple
-
Publish for the given architecture. The default is the host -architecture. The general format of the triple is -<arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for a -list of supported targets.

-

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

+
为指定架构执行 Publish 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -136,33 +145,25 @@ be specified multiple times, which enables all specified features.
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -173,9 +174,8 @@ offline.

-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
@@ -185,26 +185,25 @@ the number of CPUs.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -234,16 +233,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-report.md b/src/commands/cargo-report.md new file mode 100644 index 0000000..5df2303 --- /dev/null +++ b/src/commands/cargo-report.md @@ -0,0 +1,43 @@ +# cargo-report(1) + +## NAME + +cargo-report - Generate and display various kinds of reports + +## SYNOPSIS + +`cargo report` _type_ [_options_] + +### DESCRIPTION + +Displays a report of the given _type_ - currently, only `future-incompat` is supported + +## OPTIONS + +
+ +
--id id
+
Show the report with the specified Cargo-generated id
+ + +
-p spec...
+
--package spec...
+
Only display a report for the specified package
+ + +
+ +## EXAMPLES + +1. Display the latest future-incompat report: + + cargo report future-incompat + +2. Display the latest future-incompat report for a specific package: + + cargo report future-incompat --package my-dep:0.0.1 + +## SEE ALSO +[Future incompat report](../reference/future-incompat-report.html) + +[cargo(1)](cargo.html) diff --git a/src/commands/cargo-run.md b/src/commands/cargo-run.md index 938d8ef..d54e559 100644 --- a/src/commands/cargo-run.md +++ b/src/commands/cargo-run.md @@ -54,29 +54,26 @@ section of `Cargo.toml` to choose the name of the binary to run by default.
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -87,22 +84,31 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Run 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Run optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Run optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
+ + + +
--profile name
+
Run with the given profile. +See the the reference for more details on profiles.
+ + + +
--ignore-rust-version
+
Run the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -112,10 +118,9 @@ selection.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -126,26 +131,25 @@ Defaults to target in the root of the workspace.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -181,33 +185,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -242,41 +238,21 @@ for more information about how toolchain overrides work.
-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-## 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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-rustc.md b/src/commands/cargo-rustc.md index 002ef1a..bd4cad7 100644 --- a/src/commands/cargo-rustc.md +++ b/src/commands/cargo-rustc.md @@ -123,29 +123,26 @@ manifest settings for the target.
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -156,22 +153,41 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Build 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Build optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Build optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
+ + + +
--profile name
+
Build with the given profile.

+

The rustc subcommand will treat the following named profiles with special behaviors:

+
    +
  • check — Builds in the same way as the cargo-check(1) command with +the dev profile.
    • +
  • test — Builds in the same way as the cargo-test(1) command, +enabling building in test mode which will enable tests and enable the test +cfg option. See rustc +tests for more detail.
    • +
  • bench — Builds in the same was as the cargo-bench(1) command, +similar to the test profile.
    • +
+

See the the reference for more details on profiles.

+ + +
--ignore-rust-version
+
Build the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -181,10 +197,9 @@ selection.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -195,26 +210,25 @@ Defaults to target in the root of the workspace.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -250,33 +264,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -311,41 +317,27 @@ for more information about how toolchain overrides work.
-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.
- - -
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-## 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. +
--future-incompat-report
+
Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command

+

See cargo-report(1)

-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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-rustdoc.md b/src/commands/cargo-rustdoc.md index cbd3db6..bbf46aa 100644 --- a/src/commands/cargo-rustdoc.md +++ b/src/commands/cargo-rustdoc.md @@ -38,7 +38,9 @@ or the `build.rustdocflags` [config value](../reference/config.html).
--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.
+browser unless you define another one in the BROWSER environment variable +or use the doc.browser configuration +option.
@@ -136,29 +138,26 @@ manifest settings for the target.
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -169,22 +168,31 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Document 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Document optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Document optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
+ + + +
--profile name
+
Document with the given profile. +See the the reference for more details on profiles.
+ + + +
--ignore-rust-version
+
Document the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -194,10 +202,9 @@ selection.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -207,26 +214,25 @@ Defaults to target in the root of the workspace.
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -260,33 +266,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -320,41 +318,21 @@ for more information about how toolchain overrides work.
-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
-## 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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-search.md b/src/commands/cargo-search.md index e68d899..b783172 100644 --- a/src/commands/cargo-search.md +++ b/src/commands/cargo-search.md @@ -44,26 +44,25 @@ which is defined by the registry.default config key which defaults
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -93,16 +92,15 @@ for more information about how toolchain overrides work.
-## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-test.md b/src/commands/cargo-test.md index 8b4e2bd..f00470f 100644 --- a/src/commands/cargo-test.md +++ b/src/commands/cargo-test.md @@ -19,7 +19,8 @@ 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` and check out the rustc book's chapter on +how tests work at . As an example, this will filter for tests with `foo` in their name and run them on 3 threads in parallel: @@ -61,46 +62,38 @@ 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. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。
-p spec...
--package spec...
-
Test only the specified packages. See cargo-pkgid(1) for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like *, ? and []. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern.
+
Test指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
--workspace
-
Test all members in the workspace.
+
Test 工作区中的全体成员.
--all
-
Deprecated alias for --workspace.
+
--workspace的已废弃的别名。
--exclude SPEC...
-
Exclude the specified packages. Must be used in conjunction with the ---workspace flag. This flag may be specified multiple times and supports -common Unix glob patterns like *, ? and []. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern.
+
排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
@@ -216,29 +209,26 @@ target options.
-### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
--features features
-
Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
+
传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
--all-features
-
Activate all available features of all selected packages.
+
为给定的包启用全部可用特性
--no-default-features
-
Do not activate the default feature of the selected packages.
+
不启用给定包的default特性
@@ -249,22 +239,31 @@ be specified multiple times, which enables all specified features.
--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.

+
为指定架构执行 Test 。默认情况下为本机的架构。三元组的格式为 +<arch><sub>-<vendor>-<sys>-<abi>。执行 rustc --print target-list +可得到支持的构建目标列表。

+

也可通过build.target指定(config value)。

+

注意，指定该标志参数会使Cargo产生的构建工件放在与平常不同的目录下。 +详情参见build cache

+
-r
--release
-
Test optimized artifacts with the release profile. See the -PROFILES section for details on how this affects profile -selection.
+
Test optimized artifacts with the release profile. +See also the --profile option for choosing a specific profile by name.
+ + + +
--profile name
+
Test with the given profile. +See the the reference for more details on profiles.
+ + + +
--ignore-rust-version
+
Test the target even if the selected Rust compiler is older than the +required Rust version as configured in the project's rust-version field.
@@ -274,10 +273,9 @@ selection.
--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.
+
用于存放生成的工件以及中间文件的目录。也可通过环境变量CARGO_TARGET_DIR 或 +build.target-dir config value指定。

+

默认情况下为根工作区中的target目录。

@@ -294,26 +292,25 @@ results readable. Test output can be recovered (e.g., for debugging) by passing
-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 +
启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
-q
--quiet
-
No output printed to stdout.
+
不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
--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.
    • +
  • auto (默认)：自动检测终端是否支持带颜色的输出。
    • +
  • always：总显示带颜色的输出。
    • +
  • never：从不显示带颜色的输出。
-

May also be specified with the term.color +

也可通过term.color指定。 config value.

@@ -349,33 +346,25 @@ coming from rustc are still emitted. Cannot be used with human or <
--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.
+
用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
--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.

+
这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

+

这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

+
禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

+

注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

+

也可以通过 net.offline config value指定。

@@ -417,50 +406,28 @@ includes an option to control the number of threads used:
-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.
+
要并行运行的作业数量。也可通过build.jobs config value指定。 +默认为CPU数量。
+
--future-incompat-report
+
Displays a future-incompat report for any future-incompatible warnings +produced during execution of this command

+

See cargo-report(1)

-
- -## 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. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-tree.md b/src/commands/cargo-tree.md index ff50f50..fbd778d 100644 --- a/src/commands/cargo-tree.md +++ b/src/commands/cargo-tree.md @@ -71,6 +71,15 @@ flag can be used to display the package's reverse dependencies only with the subtree of the package given to -p. +
--prune spec
+
Prune the given package from the display of the dependency tree.
+ + +
--depth depth
+
Maximum display depth of the dependency tree. A depth of 1 displays the direct +dependencies, for example.
+ +
--no-dedupe
Do not de-duplicate repeated dependencies. Usually, when a package has already displayed its dependencies, further occurrences will not re-display its @@ -103,8 +112,10 @@ kind given, then it will automatically include the other dependency kinds.
  • no-normal — Do not include normal dependencies.
  • no-build — Do not include build dependencies.
  • no-dev — Do not include development dependencies.
    • +
  • no-proc-macro — Do not include procedural macro dependencies.
    • -

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

    +

    The normal, build, dev, and all dependency kinds cannot be mixed with +no-normal, no-build, or no-dev dependency kinds.

    The default is normal,build,dev.

    @@ -134,6 +145,7 @@ strings will be replaced with the corresponding value:

  • {l} — The package license.
  • {r} — The package repository URL.
  • {f} — Comma-separated list of package features that are enabled.
    • +
  • {lib} — The name, as used in a use statement, of the package's library.
    • @@ -148,42 +160,34 @@ strings will be replaced with the corresponding value:

    -### 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. +默认情况下，如果没有指定包，则根据清单文件来选择包(如果没有通过`--manifest-path`给出清单文件路径， +则基于当前工作目录进行寻找)。如果是某个工作区的根清单，则选中该工作区的默认成员；否则仅选中清 +单所定义的那个包。 -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. +工作区的默认成员可通过清单中`workspace.default-members`项来显式指定。如果未指定，则其虚拟 +工作区会包含全体工作区成员(等同于传递`--workspace`标志参数时)，而非虚拟工作区则仅包含根部箱自身。
    -p spec...
    --package spec...
    -
    Display only the specified packages. See cargo-pkgid(1) for the -SPEC format. This flag may be specified multiple times and supports common Unix -glob patterns like *, ? and []. However, to avoid your shell accidentally -expanding glob patterns before Cargo handles them, you must use single quotes or -double quotes around each pattern.
    +
    Display指定包. SPEC的格式参见 cargo-pkgid(1) 。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
    --workspace
    -
    Display all members in the workspace.
    +
    Display 工作区中的全体成员.
    --exclude SPEC...
    -
    Exclude the specified packages. Must be used in conjunction with the ---workspace flag. This flag may be specified multiple times and supports -common Unix glob patterns like *, ? and []. However, to avoid your shell -accidentally expanding glob patterns before Cargo handles them, you must use -single quotes or double quotes around each pattern.
    +
    排除指定包。必须与--workspace标志参数共同使用。 +此标志参数可多次使用且支持Unix通配符(*, ? 和 [])。不过，为避免shell可能错误地在Cargo获取到 +之前就将通配符展开，应在各个模式串两侧使用单引号或双引号。
    @@ -194,61 +198,50 @@ single quotes or double quotes around each pattern.
    --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.
    +
    用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
    --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.

    +
    这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

    +

    这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

    +
    禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

    +

    注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

    +

    也可以通过 net.offline config value指定。

    -### Feature Selection +### 特性选择 -The feature flags allow you to control which features are enabled. When no -feature options are given, the `default` feature is activated for every -selected package. +可通过传递特性参数来控制启用哪些特性。如果没有给定要使用的特性， +则每个已选择的包都会自动使用`default`特性。 -See [the features documentation](../reference/features.html#command-line-feature-options) -for more details. +详见[the features documentation](../reference/features.html#command-line-feature-options)。
    --features features
    -
    Space or comma separated list of features to activate. Features of workspace -members may be enabled with package-name/feature-name syntax. This flag may -be specified multiple times, which enables all specified features.
    +
    传递以空格或者逗号分隔的列表，其中给出要启用的特性。工作区成员的特性可通过包名/特性名的语法启用。 +此参数可多次给定，以分别启用给定的特性。
    --all-features
    -
    Activate all available features of all selected packages.
    +
    为给定的包启用全部可用特性
    --no-default-features
    -
    Do not activate the default feature of the selected packages.
    +
    不启用给定包的default特性
    @@ -260,26 +253,25 @@ be specified multiple times, which enables all specified features.
    -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 +
    启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
    -q
    --quiet
    -
    No output printed to stdout.
    +
    不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
    --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.
      • +
    • auto (默认)：自动检测终端是否支持带颜色的输出。
      • +
    • always：总显示带颜色的输出。
      • +
    • never：从不显示带颜色的输出。
    -

    May also be specified with the term.color +

    也可通过term.color指定。 config value.

    @@ -310,16 +302,15 @@ for more information about how toolchain overrides work. -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-uninstall.md b/src/commands/cargo-uninstall.md index 1fe35d2..65d97ef 100644 --- a/src/commands/cargo-uninstall.md +++ b/src/commands/cargo-uninstall.md @@ -53,26 +53,25 @@ The installation root is determined, in order of precedence:
    -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 +
    启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
    -q
    --quiet
    -
    No output printed to stdout.
    +
    不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
    --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.
      • +
    • auto (默认)：自动检测终端是否支持带颜色的输出。
      • +
    • always：总显示带颜色的输出。
      • +
    • never：从不显示带颜色的输出。
    -

    May also be specified with the term.color +

    也可通过term.color指定。 config value.

    @@ -103,16 +102,15 @@ for more information about how toolchain overrides work. -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-update.md b/src/commands/cargo-update.md index 8b974d7..3bf8ea6 100644 --- a/src/commands/cargo-update.md +++ b/src/commands/cargo-update.md @@ -62,26 +62,25 @@ numbers in Cargo.toml.
    -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 +
    启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
    -q
    --quiet
    -
    No output printed to stdout.
    +
    不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
    --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.
      • +
    • auto (默认)：自动检测终端是否支持带颜色的输出。
      • +
    • always：总显示带颜色的输出。
      • +
    • never：从不显示带颜色的输出。
    -

    May also be specified with the term.color +

    也可通过term.color指定。 config value.

    @@ -92,33 +91,25 @@ terminal.
    --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.
    +
    用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
    --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.

    +
    这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

    +

    这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

    +
    禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

    +

    注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

    +

    也可以通过 net.offline config value指定。

    @@ -148,16 +139,15 @@ for more information about how toolchain overrides work.
    -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-vendor.md b/src/commands/cargo-vendor.md index 91e10ae..8a8d297 100644 --- a/src/commands/cargo-vendor.md +++ b/src/commands/cargo-vendor.md @@ -56,33 +56,25 @@ only a subset of the packages have changed.
    --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.
    +
    用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
    --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.

    +
    这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

    +

    这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

    +
    禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

    +

    注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

    +

    也可以通过 net.offline config value指定。

    @@ -94,26 +86,25 @@ offline.

    -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 +
    启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
    -q
    --quiet
    -
    No output printed to stdout.
    +
    不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
    --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.
      • +
    • auto (默认)：自动检测终端是否支持带颜色的输出。
      • +
    • always：总显示带颜色的输出。
      • +
    • never：从不显示带颜色的输出。
    -

    May also be specified with the term.color +

    也可通过term.color指定。 config value.

    @@ -144,16 +135,15 @@ for more information about how toolchain overrides work.
    -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo-verify-project.md b/src/commands/cargo-verify-project.md index d077c8a..4065b29 100644 --- a/src/commands/cargo-verify-project.md +++ b/src/commands/cargo-verify-project.md @@ -27,26 +27,25 @@ An invalid workspace will display:
    -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 +
    启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
    -q
    --quiet
    -
    No output printed to stdout.
    +
    不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
    --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.
      • +
    • auto (默认)：自动检测终端是否支持带颜色的输出。
      • +
    • always：总显示带颜色的输出。
      • +
    • never：从不显示带颜色的输出。
    -

    May also be specified with the term.color +

    也可通过term.color指定。 config value.

    @@ -58,33 +57,25 @@ terminal.
    --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.
    +
    用于指定Cargo.toml文件的路径。默认情况下，Cargo会在当前目录或上级目录中寻找Cargo.toml文件。
    --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.

    +
    这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

    +

    这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

    +
    禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

    +

    注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

    +

    也可以通过 net.offline config value指定。

    @@ -114,10 +105,9 @@ for more information about how toolchain overrides work.
    -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) ## EXIT STATUS diff --git a/src/commands/cargo-yank.md b/src/commands/cargo-yank.md index c8b21e5..2d058bc 100644 --- a/src/commands/cargo-yank.md +++ b/src/commands/cargo-yank.md @@ -71,26 +71,25 @@ which is defined by the registry.default config key which defaults
    -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 +
    启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
    -q
    --quiet
    -
    No output printed to stdout.
    +
    不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
    --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.
      • +
    • auto (默认)：自动检测终端是否支持带颜色的输出。
      • +
    • always：总显示带颜色的输出。
      • +
    • never：从不显示带颜色的输出。
    -

    May also be specified with the term.color +

    也可通过term.color指定。 config value.

    @@ -121,16 +120,15 @@ for more information about how toolchain overrides work.
    -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## EXAMPLES diff --git a/src/commands/cargo.md b/src/commands/cargo.md index 400307a..370653e 100644 --- a/src/commands/cargo.md +++ b/src/commands/cargo.md @@ -152,26 +152,25 @@ error message (for example, E0004).
    -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 +
    启用更加详细的输出。可两次使用来显示"非常详细"的输出，其中包含了诸如 依赖警告 以及 构建脚本输出 等额外的输出内容。 +也可通过term.verbose指定。 config value.
    -q
    --quiet
    -
    No output printed to stdout.
    +
    不输出Cargo的日志信息。也可通过term.quiet指定。 +config value.
    --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.
      • +
    • auto (默认)：自动检测终端是否支持带颜色的输出。
      • +
    • always：总显示带颜色的输出。
      • +
    • never：从不显示带颜色的输出。
    -

    May also be specified with the term.color +

    也可通过term.color指定。 config value.

    @@ -183,26 +182,19 @@ terminal.
    --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.

    +
    这两个选项用于保证Cargo.lock文件是最新的。如果该锁文件不存在，或者不是最新的，Cargo +会报错退出。其中--frozen选项会阻止Cargo访问网络以检查锁文件是否是最新的。

    +

    这些选项，可用于保证Cargo.lock文件是最新的(比如持续集成的构建过程)， +或用于避免联网。

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

    +
    禁止Cargo访问网络。如果不添加此选项，Cargo在需要访问网络但网络不可用的情况下，会报错 +并停止工作。添加此选项后，Cargo会尽可能尝试不使用网络来工作。

    +

    注意，在此情况下可能会产生与联网状态下不同的依赖解析(Dependency Resolution)结果。 +Cargo只会使用本地已下载的crate，即便本地的索引副本中表明可能有新版本crate。在离线前下载 +所需依赖的方法，参见 cargo-fetch(1) 。

    +

    也可以通过 net.offline config value指定。

    @@ -231,16 +223,15 @@ for more information about how toolchain overrides work. -## ENVIRONMENT +## 环境 -See [the reference](../reference/environment-variables.html) for -details on environment variables that Cargo reads. +关于Cargo所读取的环境变量，可参见[the reference](../reference/environment-variables.html) -## EXIT STATUS +## 退出状态 -* `0`: Cargo succeeded. -* `101`: Cargo failed to complete. +* `0`: Cargo命令执行成功 +* `101`: Cargo命令未能完成. ## FILES