├── .gitignore ├── src ├── commands │ ├── package-commands.zh.md │ ├── manifest-commands.zh.md │ ├── publishing-commands.zh.md │ ├── general-commands.md │ ├── general-commands.zh.md │ ├── package-commands.md │ ├── publishing-commands.md │ ├── index.md │ ├── index.zh.md │ ├── manifest-commands.md │ ├── cargo-help.zh.md │ ├── build-commands.md │ ├── cargo-help.md │ ├── build-commands.zh.md │ ├── cargo-version.zh.md │ ├── cargo-version.md │ ├── cargo-report.zh.md │ ├── cargo-report.md │ ├── cargo-login.zh.md │ ├── cargo-login.md │ ├── cargo-search.zh.md │ ├── cargo-uninstall.zh.md │ ├── cargo-search.md │ ├── cargo-locate-project.zh.md │ ├── cargo-locate-project.md │ └── cargo-uninstall.md ├── favicon.ico ├── images │ ├── forkme.png │ ├── org-level-acl.png │ ├── Cargo-Logo-Small.png │ └── auth-level-acl.png ├── getting-started │ ├── index.zh.md │ ├── index.md │ ├── installation.zh.md │ ├── installation.md │ ├── first-steps.zh.md │ └── first-steps.md ├── guide │ ├── index.zh.md │ ├── working-on-an-existing-project.zh.md │ ├── index.md │ ├── working-on-an-existing-project.md │ ├── tests.zh.md │ ├── why-cargo-exists.zh.md │ ├── tests.md │ ├── project-layout.zh.md │ ├── creating-a-new-project.zh.md │ ├── project-layout.md │ ├── dependencies.zh.md │ ├── cargo-toml-vs-cargo-lock.zh.md │ ├── cargo-home.zh.md │ ├── creating-a-new-project.md │ ├── dependencies.md │ ├── continuous-integration.zh.md │ ├── why-cargo-exists.md │ ├── continuous-integration.md │ ├── cargo-toml-vs-cargo-lock.md │ └── cargo-home.md ├── reference │ ├── future-incompat-report.zh.md │ ├── index.zh.md │ ├── index.md │ ├── future-incompat-report.md │ ├── pkgid-spec.zh.md │ ├── external-tools.zh.md │ ├── workspaces.zh.md │ ├── source-replacement.zh.md │ ├── pkgid-spec.md │ ├── config.zh.md │ └── publishing.zh.md ├── index.zh.md ├── appendix │ ├── git-authentication.zh.md │ ├── git-authentication.md │ └── glossary.zh.md ├── index.md ├── SUMMARY.en.md ├── SUMMARY.md └── faq.zh.md ├── docs ├── .nojekyll ├── favicon.ico ├── favicon.png ├── images │ ├── forkme.png │ ├── auth-level-acl.png │ ├── org-level-acl.png │ └── Cargo-Logo-Small.png ├── FontAwesome │ └── fonts │ │ ├── FontAwesome.ttf │ │ ├── fontawesome-webfont.eot │ │ ├── fontawesome-webfont.ttf │ │ ├── fontawesome-webfont.woff │ │ └── fontawesome-webfont.woff2 ├── fonts │ ├── open-sans-v17-all-charsets-300.woff2 │ ├── open-sans-v17-all-charsets-600.woff2 │ ├── open-sans-v17-all-charsets-700.woff2 │ ├── open-sans-v17-all-charsets-800.woff2 │ ├── open-sans-v17-all-charsets-italic.woff2 │ ├── open-sans-v17-all-charsets-regular.woff2 │ ├── open-sans-v17-all-charsets-300italic.woff2 │ ├── open-sans-v17-all-charsets-600italic.woff2 │ ├── open-sans-v17-all-charsets-700italic.woff2 │ ├── open-sans-v17-all-charsets-800italic.woff2 │ ├── source-code-pro-v11-all-charsets-500.woff2 │ ├── fonts.css │ └── SOURCE-CODE-PRO-LICENSE.txt ├── css │ ├── print.css │ └── general.css ├── ayu-highlight.css ├── highlight.css ├── favicon.svg └── tomorrow-night.css ├── contrib ├── src │ ├── architecture │ │ ├── index.md │ │ ├── subcommands.md │ │ ├── compilation.md │ │ ├── console.md │ │ └── files.md │ ├── SUMMARY.md │ ├── tests │ │ ├── index.md │ │ ├── profiling.md │ │ └── running.md │ ├── index.md │ └── process │ │ └── unstable.md └── README.md ├── sync-en.sh ├── LICENSE-MIT ├── book.toml ├── en.md └── .mds-list /.gitignore: -------------------------------------------------------------------------------- 1 | source 2 | hello_world 3 | cargo-source -------------------------------------------------------------------------------- /src/commands/package-commands.zh.md: -------------------------------------------------------------------------------- 1 | # Package Commands 2 | -------------------------------------------------------------------------------- /src/commands/manifest-commands.zh.md: -------------------------------------------------------------------------------- 1 | # Manifest Commands 2 | -------------------------------------------------------------------------------- /src/commands/publishing-commands.zh.md: -------------------------------------------------------------------------------- 1 | # Publishing Commands 2 | -------------------------------------------------------------------------------- /docs/.nojekyll: -------------------------------------------------------------------------------- 1 | This file makes sure that Github Pages doesn't process mdBook's output. 2 | -------------------------------------------------------------------------------- /docs/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/favicon.ico -------------------------------------------------------------------------------- /docs/favicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/favicon.png -------------------------------------------------------------------------------- /src/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/src/favicon.ico -------------------------------------------------------------------------------- /src/images/forkme.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/src/images/forkme.png -------------------------------------------------------------------------------- /docs/images/forkme.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/images/forkme.png -------------------------------------------------------------------------------- /src/images/org-level-acl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/src/images/org-level-acl.png -------------------------------------------------------------------------------- /docs/images/auth-level-acl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/images/auth-level-acl.png -------------------------------------------------------------------------------- /docs/images/org-level-acl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/images/org-level-acl.png -------------------------------------------------------------------------------- /src/images/Cargo-Logo-Small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/src/images/Cargo-Logo-Small.png -------------------------------------------------------------------------------- /src/images/auth-level-acl.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/src/images/auth-level-acl.png -------------------------------------------------------------------------------- /docs/images/Cargo-Logo-Small.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/images/Cargo-Logo-Small.png -------------------------------------------------------------------------------- /docs/FontAwesome/fonts/FontAwesome.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/FontAwesome/fonts/FontAwesome.ttf -------------------------------------------------------------------------------- /docs/FontAwesome/fonts/fontawesome-webfont.eot: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/FontAwesome/fonts/fontawesome-webfont.eot -------------------------------------------------------------------------------- /docs/FontAwesome/fonts/fontawesome-webfont.ttf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/FontAwesome/fonts/fontawesome-webfont.ttf -------------------------------------------------------------------------------- /docs/FontAwesome/fonts/fontawesome-webfont.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/FontAwesome/fonts/fontawesome-webfont.woff -------------------------------------------------------------------------------- /docs/FontAwesome/fonts/fontawesome-webfont.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/FontAwesome/fonts/fontawesome-webfont.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-300.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-300.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-600.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-600.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-700.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-700.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-800.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-800.woff2 -------------------------------------------------------------------------------- /src/commands/general-commands.md: -------------------------------------------------------------------------------- 1 | # General Commands 2 | 3 | - [cargo](cargo.md) 4 | - [cargo help](cargo-help.md) 5 | - [cargo version](cargo-version.md) 6 | -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-italic.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-regular.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-300italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-300italic.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-600italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-600italic.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-700italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-700italic.woff2 -------------------------------------------------------------------------------- /docs/fonts/open-sans-v17-all-charsets-800italic.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/open-sans-v17-all-charsets-800italic.woff2 -------------------------------------------------------------------------------- /docs/fonts/source-code-pro-v11-all-charsets-500.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/chinanf-boy/cargo-book-zh/HEAD/docs/fonts/source-code-pro-v11-all-charsets-500.woff2 -------------------------------------------------------------------------------- /src/commands/general-commands.zh.md: -------------------------------------------------------------------------------- 1 | # General Commands 2 | 3 | - [cargo](cargo.zh.md) 4 | - [cargo help](cargo-help.zh.md) 5 | - [cargo version](cargo-version.zh.md) 6 | -------------------------------------------------------------------------------- /src/commands/package-commands.md: -------------------------------------------------------------------------------- 1 | # Package Commands 2 | * [cargo init](cargo-init.md) 3 | * [cargo install](cargo-install.md) 4 | * [cargo new](cargo-new.md) 5 | * [cargo search](cargo-search.md) 6 | * [cargo uninstall](cargo-uninstall.md) 7 | -------------------------------------------------------------------------------- /src/commands/publishing-commands.md: -------------------------------------------------------------------------------- 1 | # Publishing Commands 2 | * [cargo login](cargo-login.md) 3 | * [cargo owner](cargo-owner.md) 4 | * [cargo package](cargo-package.md) 5 | * [cargo publish](cargo-publish.md) 6 | * [cargo yank](cargo-yank.md) 7 | -------------------------------------------------------------------------------- /src/commands/index.md: -------------------------------------------------------------------------------- 1 | # Cargo Commands 2 | 3 | - [General Commands](general-commands.md) 4 | - [Build Commands](build-commands.md) 5 | - [Manifest Commands](manifest-commands.md) 6 | - [Package Commands](package-commands.md) 7 | - [Publishing Commands](publishing-commands.md) 8 | -------------------------------------------------------------------------------- /src/getting-started/index.zh.md: -------------------------------------------------------------------------------- 1 | ## Getting Started 2 | 3 | 要开始使用 Cargo，请安装 Cargo(和 Rust)，并设置您的第一个[_crate_][def-crate]. 4 | 5 | - [安装](./installation.zh.md) 6 | - [Cargo 的第一步](./first-steps.zh.md) 7 | 8 | [def-crate]: ../appendix/glossary.zh.md#crate '"crate" (glossary entry)' 9 | -------------------------------------------------------------------------------- /src/commands/index.zh.md: -------------------------------------------------------------------------------- 1 | # Cargo Commands 2 | 3 | - [General Commands](general-commands.zh.md) 4 | - [Build Commands](build-commands.zh.md) 5 | - [Manifest Commands](manifest-commands.zh.md) 6 | - [Package Commands](package-commands.zh.md) 7 | - [Publishing Commands](publishing-commands.zh.md) 8 | -------------------------------------------------------------------------------- /src/getting-started/index.md: -------------------------------------------------------------------------------- 1 | ## Getting Started 2 | 3 | To get started with Cargo, install Cargo (and Rust) and set up your first 4 | [*crate*][def-crate]. 5 | 6 | * [Installation](installation.md) 7 | * [First steps with Cargo](first-steps.md) 8 | 9 | [def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' 10 | -------------------------------------------------------------------------------- /contrib/src/architecture/index.md: -------------------------------------------------------------------------------- 1 | # Architecture Overview 2 | 3 | This chapter gives a very high-level overview of Cargo's architecture. This is 4 | intended to give you links into the code which is hopefully commented with 5 | more in-depth information. 6 | 7 | If you feel something is missing that would help you, feel free to ask on 8 | Zulip. 9 | -------------------------------------------------------------------------------- /src/commands/manifest-commands.md: -------------------------------------------------------------------------------- 1 | # Manifest Commands 2 | * [cargo generate-lockfile](cargo-generate-lockfile.md) 3 | * [cargo locate-project](cargo-locate-project.md) 4 | * [cargo metadata](cargo-metadata.md) 5 | * [cargo pkgid](cargo-pkgid.md) 6 | * [cargo tree](cargo-tree.md) 7 | * [cargo update](cargo-update.md) 8 | * [cargo vendor](cargo-vendor.md) 9 | * [cargo verify-project](cargo-verify-project.md) 10 | -------------------------------------------------------------------------------- /src/commands/cargo-help.zh.md: -------------------------------------------------------------------------------- 1 | # cargo-help(1) 2 | 3 | ## NAME 4 | 5 | Cargo-help - 获得 Cargo 帮助信息 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo help` [_subcommand_] 10 | 11 | ## DESCRIPTION 12 | 13 | 打印给定命令的帮助消息。 14 | 15 | ## EXAMPLES 16 | 17 | 1. 获取命令帮助： 18 | 19 | ```bash 20 | cargo help build 21 | ``` 22 | 23 | 2. 也可以通过`--help`选项： 24 | 25 | ```bash 26 | cargo build --help 27 | ``` 28 | 29 | ## SEE ALSO 30 | 31 | [cargo(1)](cargo.zh.md) 32 | -------------------------------------------------------------------------------- /src/commands/build-commands.md: -------------------------------------------------------------------------------- 1 | # Build Commands 2 | * [cargo bench](cargo-bench.md) 3 | * [cargo build](cargo-build.md) 4 | * [cargo check](cargo-check.md) 5 | * [cargo clean](cargo-clean.md) 6 | * [cargo doc](cargo-doc.md) 7 | * [cargo fetch](cargo-fetch.md) 8 | * [cargo fix](cargo-fix.md) 9 | * [cargo run](cargo-run.md) 10 | * [cargo rustc](cargo-rustc.md) 11 | * [cargo rustdoc](cargo-rustdoc.md) 12 | * [cargo test](cargo-test.md) 13 | * [cargo report](cargo-report.md) 14 | -------------------------------------------------------------------------------- /src/commands/cargo-help.md: -------------------------------------------------------------------------------- 1 | # cargo-help(1) 2 | 3 | ## NAME 4 | 5 | cargo-help - Get help for a Cargo command 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo help` [_subcommand_] 10 | 11 | ## DESCRIPTION 12 | 13 | Prints a help message for the given command. 14 | 15 | ## EXAMPLES 16 | 17 | 1. Get help for a command: 18 | 19 | cargo help build 20 | 21 | 2. Help is also available with the `--help` flag: 22 | 23 | cargo build --help 24 | 25 | ## SEE ALSO 26 | [cargo(1)](cargo.zh.md) 27 | -------------------------------------------------------------------------------- /src/commands/build-commands.zh.md: -------------------------------------------------------------------------------- 1 | # Build Commands 2 | 3 | - [cargo bench](cargo-bench.zh.md) 4 | - [cargo build](cargo-build.zh.md) 5 | - [cargo check](cargo-check.zh.md) 6 | - [cargo clean](cargo-clean.zh.md) 7 | - [cargo doc](cargo-doc.zh.md) 8 | - [cargo fetch](cargo-fetch.zh.md) 9 | - [cargo fix](cargo-fix.zh.md) 10 | - [cargo run](cargo-run.zh.md) 11 | - [cargo rustc](cargo-rustc.zh.md) 12 | - [cargo rustdoc](cargo-rustdoc.zh.md) 13 | - [cargo test](cargo-test.zh.md) 14 | - [cargo report](cargo-report.zh.md) 15 | -------------------------------------------------------------------------------- /src/guide/index.zh.md: -------------------------------------------------------------------------------- 1 | ## Cargo Guide 2 | 3 | 本指南将为您提供有关如何使用 Cargo 开发 Rust 包的所有信息. 4 | 5 | - [为什么 Cargo 存在](./why-cargo-exists.zh.md) 6 | - [创建一个新包](./creating-a-new-project.zh.md) 7 | - [使用现有的 Cargo 箱子](./working-on-an-existing-project.zh.md) 8 | - [依赖](./dependencies.zh.md) 9 | - [项目布局](./project-layout.zh.md) 10 | - [Cargo.toml 与 Cargo.lock](./cargo-toml-vs-cargo-lock.zh.md) 11 | - [测试](./tests.zh.md) 12 | - [持续集成](./continuous-integration.zh.md) 13 | - [Cargo Home](./cargo-home.zh.md) 14 | - [构建的缓存](./build-cache.zh.md) 15 | -------------------------------------------------------------------------------- /src/guide/working-on-an-existing-project.zh.md: -------------------------------------------------------------------------------- 1 | ## 在现有的 Carog 项目上工作 2 | 3 | 如果您下载使用 Cargo 的现有[package][def-package]，那么它很容易上手. 4 | 5 | 首先，从某个地方获取项目.在这个例子中，我们将使用`rand`项目，其从 GitHub 上的存储库克隆而来: 6 | 7 | ```shell 8 | $ git clone https://github.com/rust-lang-nursery/rand.git 9 | $ cd rand 10 | ``` 11 | 12 | 要建立，使用`cargo build`: 13 | 14 | ```shell 15 | $ cargo build 16 | Compiling rand v0.1.0 (file:///path/to/project/rand) 17 | ``` 18 | 19 | 这将获取所有依赖项，然后与项目一起构建它们. 20 | 21 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 22 | -------------------------------------------------------------------------------- /contrib/README.md: -------------------------------------------------------------------------------- 1 | # Cargo Contributor Guide 2 | 3 | This is the source of the Cargo Contributor Guide, published at 4 | . It is written in Markdown, using 5 | the [mdbook] tool to convert to HTML. If you are editing these pages, the best 6 | option to view the results is to run `mdbook serve`, which will start a web 7 | server on localhost that you can visit to view the book, and it will 8 | automatically reload each time you edit a page. 9 | 10 | This is published via GitHub Actions to GitHub Pages. 11 | 12 | [mdbook]: https://rust-lang.github.io/mdBook/ 13 | -------------------------------------------------------------------------------- /src/reference/future-incompat-report.zh.md: -------------------------------------------------------------------------------- 1 | ### Future incompat report 2 | 3 | Cargo检查所有依赖项中的未来不兼容警告。这些警告针对可能在将来成为硬错误的更改，导致依赖关系在未来版本的rustc中停止构建。如果发现任何警告，将显示一个小通知，指示已发现警告，并提供有关如何显示完整报告的说明。 4 | 5 | 可以使用`cargo report future-incompatibilities 6 | --id ID`命令，或者使用`--future-incompat-report`选项然后，开发人员应该将他们的依赖项更新到问题得到修复的版本，或者与依赖项的开发人员一起帮助解决问题。 7 | 8 | 此功能可以通过`[future-incompat-report]`部分`.cargo/config`。目前，受支持的选项包括： 9 | 10 | ``` 11 | [future-incompat-report] 12 | frequency = FREQUENCY 13 | ``` 14 | 15 | 的支持值`FREQUENCY`你总是`and 'never', which control 16 | whether or not a message is printed out at the end of`Cargo建造`/`Cargo检查。 17 | -------------------------------------------------------------------------------- /src/guide/index.md: -------------------------------------------------------------------------------- 1 | ## Cargo Guide 2 | 3 | This guide will give you all that you need to know about how to use Cargo to 4 | develop Rust packages. 5 | 6 | * [Why Cargo Exists](why-cargo-exists.md) 7 | * [Creating a New Package](creating-a-new-project.md) 8 | * [Working on an Existing Cargo Package](working-on-an-existing-project.md) 9 | * [Dependencies](dependencies.md) 10 | * [Package Layout](project-layout.md) 11 | * [Cargo.toml vs Cargo.lock](cargo-toml-vs-cargo-lock.md) 12 | * [Tests](tests.md) 13 | * [Continuous Integration](continuous-integration.md) 14 | * [Cargo Home](cargo-home.md) 15 | * [Build Cache](build-cache.md) 16 | -------------------------------------------------------------------------------- /src/guide/working-on-an-existing-project.md: -------------------------------------------------------------------------------- 1 | ## Working on an Existing Cargo Package 2 | 3 | If you download an existing [package][def-package] that uses Cargo, it’s 4 | really easy to get going. 5 | 6 | First, get the package from somewhere. In this example, we’ll use `regex` 7 | cloned from its repository on GitHub: 8 | 9 | ```console 10 | $ git clone https://github.com/rust-lang/regex.git 11 | $ cd regex 12 | ``` 13 | 14 | To build, use `cargo build`: 15 | 16 | ```console 17 | $ cargo build 18 | Compiling regex v1.5.0 (file:///path/to/package/regex) 19 | ``` 20 | 21 | This will fetch all of the dependencies and then build them, along with the 22 | package. 23 | 24 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 25 | -------------------------------------------------------------------------------- /sync-en.sh: -------------------------------------------------------------------------------- 1 | cat './.mds-list' | while read line 2 | do 3 | testseq="zh.md" 4 | if [[ $line =~ $testseq || "$line" == "" ]]; then 5 | echo "skip $line" 6 | else 7 | lowline=`echo "$line" | awk '{print tolower($0)}'` 8 | # lowwer string 9 | zh=${line//source\//} 10 | dir=$(dirname $zh) 11 | 12 | source_readme="./source/readme.md" 13 | if [[ $lowline == $source_readme ]];then 14 | # source/[readme|REAMDE].md => en.md 15 | filename="en.md" 16 | else 17 | # source/other.md => ./other.md 18 | filename=$(basename $zh) 19 | fi 20 | echo "$line >> $dir/$filename" 21 | mkdir -p $dir && cp $line "$_/$filename" 22 | fi 23 | done -------------------------------------------------------------------------------- /src/getting-started/installation.zh.md: -------------------------------------------------------------------------------- 1 | ## 安装 2 | 3 | ### 安装 Rust 和 Cargo 4 | 5 | 获得 Cargo 的最简单方法是使用`rustup`脚本，获取当前稳定版本的 [Rust]，它同时带上了`cargo`: 6 | 7 | 在 Linux 和 macOS 系统上，这可以通过以下方式完成: 8 | 9 | ```console 10 | curl https://sh.rustup.rs -sSf | sh 11 | ``` 12 | 13 | 它将下载一个脚本，然后开始安装。如果一切顺利，您会看到: 14 | 15 | ```console 16 | Rust is installed now. Great! 17 | ``` 18 | 19 | 在 Windows 上，下载并运行[rustup-init.exe]。它将在控制台中启动安装，并在成功时显示上述消息. 20 | 21 | 在此之后，你可以使用`rustup`命令去安装，`beta`或者`nightly`版本的 Rust 和 Cargo。 22 | 23 | 有关其他安装选项和信息，请访问 Rust 网站的[安装][install-rust]页面. 24 | 25 | ### 从源头构建 Cargo 26 | 27 | 或者，你可以[以源代码的方式，构建 Cargo][compiling-from-source]. 28 | 29 | [rust]: https://www.rust-lang.org/ 30 | [rustup-init.exe]: https://win.rustup.rs/ 31 | [install-rust]: https://www.rust-lang.org/tools/install 32 | [compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source 33 | -------------------------------------------------------------------------------- /contrib/src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | - [Introduction](./index.md) 4 | - [Issue Tracker](./issues.md) 5 | - [Process](./process/index.md) 6 | - [Working on Cargo](./process/working-on-cargo.md) 7 | - [Release process](./process/release.md) 8 | - [Unstable features](./process/unstable.md) 9 | - [Architecture](./architecture/index.md) 10 | - [Codebase Overview](./architecture/codebase.md) 11 | - [SubCommands](./architecture/subcommands.md) 12 | - [Console Output](./architecture/console.md) 13 | - [Packages and Resolution](./architecture/packages.md) 14 | - [Compilation](./architecture/compilation.md) 15 | - [Files](./architecture/files.md) 16 | - [Tests](./tests/index.md) 17 | - [Running Tests](./tests/running.md) 18 | - [Writing Tests](./tests/writing.md) 19 | - [Benchmarking and Profiling](./tests/profiling.md) 20 | - [Design Principles](./design.md) 21 | -------------------------------------------------------------------------------- /src/commands/cargo-version.zh.md: -------------------------------------------------------------------------------- 1 | # cargo-version(1) 2 | 3 | ## NAME 4 | 5 | cargo-version - 显示版本信息 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo version` [_options_] 10 | 11 | ## DESCRIPTION 12 | 13 | 显示 Cargo 的版本。 14 | 15 | ## OPTIONS 16 | 17 |
18 | 19 |
-v
20 |
--verbose
21 |
显示额外的版本信息
22 | 23 |
24 | 25 | ## EXAMPLES 26 | 27 | 1. 显示版本： 28 | 29 | ``` 30 | cargo version 31 | ``` 32 | 33 | 2. 该版本也可通过以下标志获得： 34 | 35 | ``` 36 | cargo --version 37 | cargo -V 38 | ``` 39 | 40 | 3. 显示额外的版本信息： 41 | 42 | ``` 43 | cargo -Vv 44 | ``` 45 | 46 | ## SEE ALSO 47 | 48 | [cargo(1)](cargo.zh.md) 49 | -------------------------------------------------------------------------------- /src/reference/index.zh.md: -------------------------------------------------------------------------------- 1 | ## Cargo 参考 2 | 3 | 该参考文献涵盖了 Cargo 各个领域的细节. 4 | 5 | - [指定依赖项](./specifying-dependencies.zh.md) 6 | - [覆盖依赖项](overriding-dependencies.zh.md) 7 | - [清单格式](./manifest.zh.md) 8 | - [Cargo Targets](cargo-targets.zh.md) 9 | - [Workspaces](workspaces.zh.md) 10 | - [Features](features.zh.md) 11 | - [Features 示例](features-examples.zh.md) 12 | - [Profiles](profiles.zh.md) 13 | - [配置](./config.zh.md) 14 | - [环境变量](./environment-variables.zh.md) 15 | - [构建脚本](./build-scripts.zh.md) 16 | - [Build Script 示例](build-script-examples.zh.md) 17 | - [在 crates.io 上发布](./publishing.zh.md) 18 | - [包 ID 规格](./pkgid-spec.zh.md) 19 | - [来源更换](./source-replacement.zh.md) 20 | - [外部工具](./external-tools.zh.md) 21 | - [来源](registries.zh.md) 22 | - [依赖项 解析](resolver.zh.md) 23 | - [SemVer 格式版本的 兼容性](semver.zh.md) 24 | - [Future 不兼容报告](future-incompat-report.zh.md) 25 | - [不稳定的功能](./unstable.zh.md) 26 | -------------------------------------------------------------------------------- /src/commands/cargo-version.md: -------------------------------------------------------------------------------- 1 | # cargo-version(1) 2 | 3 | ## NAME 4 | 5 | cargo-version - Show version information 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo version` [_options_] 10 | 11 | ## DESCRIPTION 12 | 13 | Displays the version of Cargo. 14 | 15 | ## OPTIONS 16 | 17 |
18 | 19 |
-v
20 |
--verbose
21 |
Display additional version information.
22 | 23 | 24 |
25 | 26 | ## EXAMPLES 27 | 28 | 1. Display the version: 29 | 30 | cargo version 31 | 32 | 2. The version is also available via flags: 33 | 34 | cargo --version 35 | cargo -V 36 | 37 | 3. Display extra version information: 38 | 39 | cargo -Vv 40 | 41 | ## SEE ALSO 42 | [cargo(1)](cargo.zh.md) 43 | -------------------------------------------------------------------------------- /src/guide/tests.zh.md: -------------------------------------------------------------------------------- 1 | ## 测试 2 | 3 | Cargo 可以使用`cargo test`命令运行您的测试。Cargo 寻找在两个地方运行的测试 :在你`src`中的每个文件，和`tests/`中的任何测试。测试你的`src`文件应该是单元测试，并在`tests/`中的应该是整合式测试。因此，您需要将[package][def-package]导入到`tests`的文件中. 4 | 5 | 这是在我们的项目中，运行`cargo test`的一个例子，目前没有测试: 6 | 7 | ```console 8 | $ cargo test 9 | Compiling regex v1.5.0 (https://github.com/rust-lang/regex.git#9f9f693) 10 | Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) 11 | Running target/test/hello_world-9c2b65bbb79eabce 12 | 13 | running 0 tests 14 | 15 | test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out 16 | ``` 17 | 18 | 如果我们的项目有测试，我们会看到更多的输出与正确的测试数量. 19 | 20 | 您还可以通过传递过滤器，来运行特定测试: 21 | 22 | ```shell 23 | $ cargo test foo 24 | ``` 25 | 26 | 这将运行任何匹配的`foo`测试. 27 | 28 | `cargo test`还运行其他检查。例如，它将编译您包含的任何示例(examples)，并且还将测试文档中的示例。请看在 Rust 文档中的[测试指南][testing]，了解更多详细信息. 29 | 30 | [def-package]: ../appendix/glossary.zh.md#package '"package" (glossary entry)' 31 | [testing]: ../../book/ch11-00-testing.html 32 | -------------------------------------------------------------------------------- /docs/css/print.css: -------------------------------------------------------------------------------- 1 | 2 | #sidebar, 3 | #menu-bar, 4 | .nav-chapters, 5 | .mobile-nav-chapters { 6 | display: none; 7 | } 8 | 9 | #page-wrapper.page-wrapper { 10 | transform: none; 11 | margin-left: 0px; 12 | overflow-y: initial; 13 | } 14 | 15 | #content { 16 | max-width: none; 17 | margin: 0; 18 | padding: 0; 19 | } 20 | 21 | .page { 22 | overflow-y: initial; 23 | } 24 | 25 | code { 26 | background-color: #666666; 27 | border-radius: 5px; 28 | 29 | /* Force background to be printed in Chrome */ 30 | -webkit-print-color-adjust: exact; 31 | } 32 | 33 | pre > .buttons { 34 | z-index: 2; 35 | } 36 | 37 | a, a:visited, a:active, a:hover { 38 | color: #4183c4; 39 | text-decoration: none; 40 | } 41 | 42 | h1, h2, h3, h4, h5, h6 { 43 | page-break-inside: avoid; 44 | page-break-after: avoid; 45 | } 46 | 47 | pre, code { 48 | page-break-inside: avoid; 49 | white-space: pre-wrap; 50 | } 51 | 52 | .fa { 53 | display: none !important; 54 | } 55 | -------------------------------------------------------------------------------- /src/reference/index.md: -------------------------------------------------------------------------------- 1 | ## Cargo Reference 2 | 3 | The reference covers the details of various areas of Cargo. 4 | 5 | * [Specifying Dependencies](specifying-dependencies.md) 6 | * [Overriding Dependencies](overriding-dependencies.md) 7 | * [The Manifest Format](manifest.md) 8 | * [Cargo Targets](cargo-targets.md) 9 | * [Workspaces](workspaces.md) 10 | * [Features](features.md) 11 | * [Features Examples](features-examples.md) 12 | * [Profiles](profiles.md) 13 | * [Configuration](config.md) 14 | * [Environment Variables](environment-variables.md) 15 | * [Build Scripts](build-scripts.md) 16 | * [Build Script Examples](build-script-examples.md) 17 | * [Publishing on crates.io](publishing.md) 18 | * [Package ID Specifications](pkgid-spec.md) 19 | * [Source Replacement](source-replacement.md) 20 | * [External Tools](external-tools.md) 21 | * [Registries](registries.md) 22 | * [Dependency Resolution](resolver.md) 23 | * [SemVer Compatibility](semver.md) 24 | * [Future incompat report](future-incompat-report.md) 25 | * [Unstable Features](unstable.md) 26 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | Copyright (c) 2010 The Rust Project Developers 2 | 3 | Permission is hereby granted, free of charge, to any 4 | person obtaining a copy of this software and associated 5 | documentation files (the "Software"), to deal in the 6 | Software without restriction, including without 7 | limitation the rights to use, copy, modify, merge, 8 | publish, distribute, sublicense, and/or sell copies of 9 | the Software, and to permit persons to whom the Software 10 | is furnished to do so, subject to the following 11 | conditions: 12 | 13 | The above copyright notice and this permission notice 14 | shall be included in all copies or substantial portions 15 | of the Software. 16 | 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 18 | ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 19 | TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 20 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 21 | SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 22 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 23 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 24 | IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 | DEALINGS IN THE SOFTWARE. 26 | -------------------------------------------------------------------------------- /contrib/src/tests/index.md: -------------------------------------------------------------------------------- 1 | # Tests 2 | 3 | Cargo has an extensive test suite. Most of it is implemented as integration 4 | tests in the [`testsuite`] directory. There are several other tests: 5 | 6 | * Unit tests are scattered throughout. 7 | * The dependency resolver has its own set of tests in the [`resolver-tests`] 8 | directory. 9 | * All of the packages in the [`crates`] directory have their own set of tests. 10 | * The [`build-std`] test is for the [build-std feature]. It is separate since 11 | it has some special requirements. 12 | * Documentation has a variety of tests, such as link validation, and the 13 | [SemVer chapter validity checks]. 14 | 15 | [`testsuite`]: https://github.com/rust-lang/cargo/tree/master/tests/testsuite/ 16 | [`resolver-tests`]: https://github.com/rust-lang/cargo/tree/master/crates/resolver-tests 17 | [`crates`]: https://github.com/rust-lang/cargo/tree/master/crates 18 | [`build-std`]: https://github.com/rust-lang/cargo/blob/master/tests/build-std/main.rs 19 | [build-std feature]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std 20 | [SemVer chapter validity checks]: https://github.com/rust-lang/cargo/tree/master/src/doc/semver-check 21 | -------------------------------------------------------------------------------- /src/reference/future-incompat-report.md: -------------------------------------------------------------------------------- 1 | ### Future incompat report 2 | 3 | Cargo checks for future-incompatible warnings in all dependencies. These are warnings for 4 | changes that may become hard errors in the future, causing the dependency to 5 | stop building in a future version of rustc. If any warnings are found, a small 6 | notice is displayed indicating that the warnings were found, and provides 7 | instructions on how to display a full report. 8 | 9 | A full report can be displayed with the `cargo report future-incompatibilities 10 | --id ID` command, or by running the build again with 11 | the `--future-incompat-report` flag. The developer should then update their 12 | dependencies to a version where the issue is fixed, or work with the 13 | developers of the dependencies to help resolve the issue. 14 | 15 | This feature can be configured through a `[future-incompat-report]` 16 | section in `.cargo/config`. Currently, the supported options are: 17 | 18 | ``` 19 | [future-incompat-report] 20 | frequency = FREQUENCY 21 | ``` 22 | 23 | The supported values for `FREQUENCY` are 'always` and 'never', which control 24 | whether or not a message is printed out at the end of `cargo build` / `cargo check`. 25 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | 2 | [book] 3 | title = "Rust Cargo 官书（非官方翻译)" 4 | description = "Cargo " 5 | authors = ["Alex Crichton, Steve Klabnik and Carol Nichols, with Contributions from the Rust Community","译文: Yobrave Lee"] 6 | multilingual = false 7 | src = "src" 8 | 9 | [build] 10 | build-dir = "docs" 11 | create-missing = true 12 | use-default-preprocessors = false 13 | 14 | [preprocessor.links] 15 | # renderers = ["html"] 16 | 17 | [output.html] 18 | mathjax-support = false 19 | theme = "theme" 20 | curly-quotes = true 21 | # google-analytics = "UA-128555056-1" 22 | # additional-css = ["theme/custom.css"] 23 | git_repository_url = "https://github.com/chinanf-boy/cargo-book-zh" 24 | git_repository_icon = "fa-github" 25 | edit-url-template = "https://github.com/chinanf-boy/cargo-book-zh/edit/master/{path}" 26 | # additional-js = ["theme/custom.js"] 27 | 28 | [output.html.playpen] 29 | # editor = "./path/to/editor" 30 | editable = false 31 | 32 | [output.html.search] 33 | enable = true 34 | # searcher = "./path/to/searcher" 35 | limit-results = 30 36 | teaser-word-count = 30 37 | use-boolean-and = true 38 | boost-title = 2 39 | boost-hierarchy = 1 40 | boost-paragraph = 1 41 | expand = true 42 | heading-split-level = 3 43 | # copy-js = true -------------------------------------------------------------------------------- /src/commands/cargo-report.zh.md: -------------------------------------------------------------------------------- 1 | # cargo-report(1) 2 | 3 | ## NAME 4 | 5 | Cargo报告-生成和显示各种报告 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo report` *类型* [_options_] 10 | 11 | ### DESCRIPTION 12 | 13 | 显示给定项目的报告*类型*-目前只有`future-incompat`支持 14 | 15 | ## OPTIONS 16 | 17 |
18 | 19 |
--id id
20 |
Show the report with the specified Cargo-generated id
21 | 22 |
-p spec...
23 |
--package spec...
24 |
Only display a report for the specified package
25 | 26 |
27 | 28 | ## EXAMPLES 29 | 30 | 1. 显示最新的未来不匹配报告： 31 | 32 | Cargo报告未来不匹配 33 | 34 | 2. 显示特定软件包的最新未来不兼容报告： 35 | 36 | Cargo报告未来不匹配——包装我的部门：0.0.1 37 | 38 | ## SEE ALSO 39 | 40 | [Future incompat report](../reference/future-incompat-report.html) 41 | 42 | [cargo(1)](cargo.zh.md) 43 | -------------------------------------------------------------------------------- /docs/ayu-highlight.css: -------------------------------------------------------------------------------- 1 | /* 2 | Based off of the Ayu theme 3 | Original by Dempfi (https://github.com/dempfi/ayu) 4 | */ 5 | 6 | .hljs { 7 | display: block; 8 | overflow-x: auto; 9 | background: #191f26; 10 | color: #e6e1cf; 11 | padding: 0.5em; 12 | } 13 | 14 | .hljs-comment, 15 | .hljs-quote { 16 | color: #5c6773; 17 | font-style: italic; 18 | } 19 | 20 | .hljs-variable, 21 | .hljs-template-variable, 22 | .hljs-attribute, 23 | .hljs-attr, 24 | .hljs-regexp, 25 | .hljs-link, 26 | .hljs-selector-id, 27 | .hljs-selector-class { 28 | color: #ff7733; 29 | } 30 | 31 | .hljs-number, 32 | .hljs-meta, 33 | .hljs-builtin-name, 34 | .hljs-literal, 35 | .hljs-type, 36 | .hljs-params { 37 | color: #ffee99; 38 | } 39 | 40 | .hljs-string, 41 | .hljs-bullet { 42 | color: #b8cc52; 43 | } 44 | 45 | .hljs-title, 46 | .hljs-built_in, 47 | .hljs-section { 48 | color: #ffb454; 49 | } 50 | 51 | .hljs-keyword, 52 | .hljs-selector-tag, 53 | .hljs-symbol { 54 | color: #ff7733; 55 | } 56 | 57 | .hljs-name { 58 | color: #36a3d9; 59 | } 60 | 61 | .hljs-tag { 62 | color: #00568d; 63 | } 64 | 65 | .hljs-emphasis { 66 | font-style: italic; 67 | } 68 | 69 | .hljs-strong { 70 | font-weight: bold; 71 | } 72 | 73 | .hljs-addition { 74 | color: #91b362; 75 | } 76 | 77 | .hljs-deletion { 78 | color: #d96c75; 79 | } 80 | -------------------------------------------------------------------------------- /src/getting-started/installation.md: -------------------------------------------------------------------------------- 1 | ## Installation 2 | 3 | ### Install Rust and Cargo 4 | 5 | The easiest way to get Cargo is to install the current stable release of [Rust] 6 | by using `rustup`. Installing Rust using `rustup` will also install `cargo`. 7 | 8 | On Linux and macOS systems, this is done as follows: 9 | 10 | ```console 11 | curl https://sh.rustup.rs -sSf | sh 12 | ``` 13 | 14 | It will download a script, and start the installation. If everything goes well, 15 | you’ll see this appear: 16 | 17 | ```console 18 | Rust is installed now. Great! 19 | ``` 20 | 21 | On Windows, download and run [rustup-init.exe]. It will start the installation 22 | in a console and present the above message on success. 23 | 24 | After this, you can use the `rustup` command to also install `beta` or `nightly` 25 | channels for Rust and Cargo. 26 | 27 | For other installation options and information, visit the 28 | [install][install-rust] page of the Rust website. 29 | 30 | ### Build and Install Cargo from Source 31 | 32 | Alternatively, you can [build Cargo from source][compiling-from-source]. 33 | 34 | [rust]: https://www.rust-lang.org/ 35 | [rustup-init.exe]: https://win.rustup.rs/ 36 | [install-rust]: https://www.rust-lang.org/tools/install 37 | [compiling-from-source]: https://github.com/rust-lang/cargo#compiling-from-source 38 | -------------------------------------------------------------------------------- /contrib/src/architecture/subcommands.md: -------------------------------------------------------------------------------- 1 | # SubCommands 2 | 3 | Cargo is a single binary composed of a set of [`clap`] subcommands. All 4 | subcommands live in [`src/bin/cargo/commands`] directory. 5 | [`src/bin/cargo/main.rs`] is the entry point. 6 | 7 | Each subcommand, such as [`src/bin/cargo/commands/build.rs`], usually performs 8 | the following: 9 | 10 | 1. Parse the CLI flags. See the [`command_prelude`] module for some helpers to make this easier. 11 | 2. Load the config files. 12 | 3. Discover and load the workspace. 13 | 4. Calls the actual implementation of the subcommand which resides in [`src/cargo/ops`]. 14 | 15 | If the subcommand is not found in the built-in list, then Cargo will 16 | automatically search for a subcommand named `cargo-{NAME}` in the users `PATH` 17 | to execute the subcommand. 18 | 19 | 20 | [`clap`]: https://clap.rs/ 21 | [`src/bin/cargo/commands/build.rs`]: https://github.com/rust-lang/cargo/tree/master/src/bin/cargo/commands/build.rs 22 | [`src/cargo/ops`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/ops 23 | [`src/bin/cargo/commands`]: https://github.com/rust-lang/cargo/tree/master/src/bin/cargo/commands 24 | [`src/bin/cargo/main.rs`]: https://github.com/rust-lang/cargo/blob/master/src/bin/cargo/main.rs 25 | [`command_prelude`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/command_prelude.rs 26 | -------------------------------------------------------------------------------- /contrib/src/index.md: -------------------------------------------------------------------------------- 1 | # Introduction 2 | 3 | Thank you for your interest in contributing to [Cargo]! This guide provides an 4 | overview of how to contribute to Cargo, how to dive into the code, and how the 5 | testing infrastructure works. 6 | 7 | There are many ways to contribute, such as [helping other users], [filing 8 | issues], [improving the documentation], [fixing bugs], and working on [small] 9 | and [large features]. 10 | 11 | If you have a general question about Cargo or its internals, feel free to ask 12 | on [Zulip]. 13 | 14 | This guide assumes you have some familiarity with Rust, and how to use Cargo, 15 | [rustup], and general development tools like [git]. 16 | 17 | Please also read the [Rust Code of Conduct]. 18 | 19 | [Cargo]: https://doc.rust-lang.org/cargo/ 20 | [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/246057-t-cargo 21 | [Rust Code of Conduct]: https://www.rust-lang.org/policies/code-of-conduct 22 | [helping other users]: https://users.rust-lang.org/ 23 | [filing issues]: issues.md 24 | [rustup]: https://rust-lang.github.io/rustup/ 25 | [git]: https://git-scm.com/ 26 | [improving the documentation]: https://github.com/rust-lang/cargo/tree/master/src/doc 27 | [fixing bugs]: process/index.md#working-on-small-bugs 28 | [small]: process/index.md#working-on-small-features 29 | [large features]: process/index.md#working-on-large-features 30 | -------------------------------------------------------------------------------- /src/guide/why-cargo-exists.zh.md: -------------------------------------------------------------------------------- 1 | ## 为什么 Cargo 存在 2 | 3 | ### 前言 4 | 5 | 在 Rust, 正如你所了解的，一个库或执行程序被叫做 箱子。而箱子是通过 Rust 编译器`rustc`所编译的。当我们与 Rust 相遇，第一个源代码回事著名的 Hello World 程序，它可以直接用`rustc`编译。 6 | 7 | ```console 8 | $ rustc hello.rs 9 | $ ./hello 10 | Hello, world! 11 | ``` 12 | 13 | 注意到，上面的命令，是需要指明文件名的。如果，我们直接使用 `rustc`，那么，命令行的调用，就会夹杂着不同的命令。更别说，特殊(更详细)的命令行选项的指定，去包括外部依赖... 14 | 15 | 更重要的是，当项目具有各种外部依赖，你要管理它们的版本，确保正确性与方便性。 16 | 17 | 为了可以做到人性化，不直接操作`rustc`，我们引入了更高的抽象工具 —— 包管理器 18 | 19 | ### 出场：Cargo 20 | 21 | Cargo 就是一个 Rust 的包管理器。允许 Rust 项目声明其各种依赖项，并确保您始终获得可重复的构建。 22 | 23 | 为了实现这一目标,Cargo 做了四件事: 24 | 25 | - 引入两个，包含各种项目信息的元数据文件。 26 | - 获取，并构建项目的依赖项. 27 | - 正确使用参数，以调用`rustc`或其他构建工具，构建你的项目。 28 | - 介绍，更容易使用 Rust 项目的约定(规范/风格)。 29 | 30 | 往大的说，Cargo 给构建一个程序，一个库，带来了一种标准化的方式，不去管项目的名字，更不需要直接调用 `rustc`，我们可以更常规地调用`cargo build`，然后，让 cargo 处理正确的`rustc`调用。Cargo 还会自动从[_registry_][def-registry]，获取我们的依赖项，安排得明明白白。 31 | 32 | 一语言之，有了 Cargo，你的 Rust 就有了垫脚石。 33 | 34 | [def-artifact]: ../appendix/glossary.zh.md#artifact '"artifact" (glossary entry)' 35 | [def-crate]: ../appendix/glossary.zh.md#crate '"crate" (glossary entry)' 36 | [def-package]: ../appendix/glossary.zh.md#package '"package" (glossary entry)' 37 | [def-package-manager]: ../appendix/glossary.zh.md#package-manager '"package manager" (glossary entry)' 38 | [def-registry]: ../appendix/glossary.zh.md#registry '"registry" (glossary entry)' 39 | -------------------------------------------------------------------------------- /src/reference/pkgid-spec.zh.md: -------------------------------------------------------------------------------- 1 | ## Package ID Specifications 2 | 3 | ### Package ID specifications 4 | 5 | 包 ID 规范 6 | 7 | Cargo 的子命令经常需要引用依赖关系图中的特定包来进行各种操作，例如更新，清理，构建等。为了解决这个问题，Cargo 支持包 ID 规范。规范是一个字符串，用于唯一地引用依赖关系图中的一个包. 8 | 9 | #### Specification grammar 10 | 11 | 规范语法 12 | 13 | 包 ID 规范的形式语法是: 14 | 15 | ```notrust 16 | pkgid := pkgname 17 | | [ proto "://" ] hostname-and-path [ "#" ( pkgname | semver ) ] 18 | pkgname := name [ ":" semver ] 19 | 20 | proto := "http" | "git" | ... 21 | ``` 22 | 23 | 这里，括号表示内容是可选的. 24 | 25 | #### Example specifications 26 | 27 | 规范示例 28 | 29 | 这些都可以是对`foo`包的引用，版本`1.2.3`，来自注册表`crates.io` 30 | 31 | | pkgid | 名称 | 版本 | 网址 | 32 | | :--------------------------- | :---: | :-----: | :--------------------: | 33 | | `foo` | `foo` | `*` | `*` | 34 | | `foo:1.2.3` | `foo` | `1.2.3` | `*` | 35 | | `crates.io/foo` | `foo` | `*` | `*://crates.io/foo` | 36 | | `crates.io/foo#1.2.3` | `foo` | `1.2.3` | `*://crates.io/foo` | 37 | | `crates.io/bar#foo:1.2.3` | `foo` | `1.2.3` | `*://crates.io/bar` | 38 | | `http://crates.io/foo#1.2.3` | `foo` | `1.2.3` | `http://crates.io/foo` | 39 | 40 | #### Brevity of specifications 41 | 42 | 规范的简洁 43 | 44 | 这样做的目的是用简洁和详尽的语法来引用依赖图中的包。而不明确的引用可以指代一个或多个包。若使用相同的规范会引用多个包，那大多数命令都会生成错误。 45 | -------------------------------------------------------------------------------- /src/commands/cargo-report.md: -------------------------------------------------------------------------------- 1 | # cargo-report(1) 2 | 3 | ## NAME 4 | 5 | cargo-report - Generate and display various kinds of reports 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo report` _type_ [_options_] 10 | 11 | ### DESCRIPTION 12 | 13 | Displays a report of the given _type_ - currently, only `future-incompat` is supported 14 | 15 | ## OPTIONS 16 | 17 |
18 | 19 |
--id id
20 |
Show the report with the specified Cargo-generated id
21 | 22 | 23 |
-p spec...
24 |
--package spec...
25 |
Only display a report for the specified package
26 | 27 | 28 |
29 | 30 | ## EXAMPLES 31 | 32 | 1. Display the latest future-incompat report: 33 | 34 | cargo report future-incompat 35 | 36 | 2. Display the latest future-incompat report for a specific package: 37 | 38 | cargo report future-incompat --package my-dep:0.0.1 39 | 40 | ## SEE ALSO 41 | [Future incompat report](../reference/future-incompat-report.html) 42 | 43 | [cargo(1)](cargo.zh.md) 44 | -------------------------------------------------------------------------------- /contrib/src/tests/profiling.md: -------------------------------------------------------------------------------- 1 | # Benchmarking and Profiling 2 | 3 | ## Internal profiler 4 | 5 | Cargo has a basic, hierarchical profiler built-in. The environment variable 6 | `CARGO_PROFILE` can be set to an integer which specifies how deep in the 7 | profile stack to print results for. 8 | 9 | ```sh 10 | # Output first three levels of profiling info 11 | CARGO_PROFILE=3 cargo generate-lockfile 12 | ``` 13 | 14 | ## Benchmarking 15 | 16 | ### Benchsuite 17 | 18 | Head over to the [`benches` 19 | directory](https://github.com/rust-lang/cargo/tree/master/benches) for more 20 | information about the benchmarking suite. 21 | 22 | ### Informal benchmarking 23 | 24 | The overhead for starting a build should be kept as low as possible 25 | (preferably, well under 0.5 seconds on most projects and systems). Currently, 26 | the primary parts that affect this are: 27 | 28 | * Running the resolver. 29 | * Querying the index. 30 | * Checking git dependencies. 31 | * Scanning the local project. 32 | * Building the unit dependency graph. 33 | 34 | One way to test this is to use [hyperfine]. This is a tool that can be used to 35 | measure the difference between different commands and settings. Usually this 36 | is done by measuring the time it takes for `cargo build` to finish in a large 37 | project where the build is fresh (no actual compilation is performed). Just 38 | run `cargo build` once before using hyperfine. 39 | 40 | [hyperfine]: https://github.com/sharkdp/hyperfine 41 | -------------------------------------------------------------------------------- /src/index.zh.md: -------------------------------------------------------------------------------- 1 | # The Cargo Book 2 | 3 | ![Cargo Logo](images/Cargo-Logo-Small.png) 4 | 5 | Cargo 是[Rust]的 _箱子经理_。Cargo 会下载所需要的依赖项，还能编译您的代码，生成可分发的箱子，并将它们上传到[crates.io] - Rust 社区的 [_package registry_][def-package-registry] 。你可以为这本书做出贡献在[GitHub]. 6 | 7 | ### 章节 8 | 9 | **[入门](getting-started/index.zh.md)** 10 | 11 | 要开始使用 Cargo，请安装 Cargo(和 Rust)并设置您的第一个箱子. 12 | 13 | **[Cargo 指南](guide/index.zh.md)** 14 | 15 | 该指南将为您提供，有关如何使用 Cargo 开发 Rust 箱子的所有信息. 16 | 17 | **[Cargo 参考](reference/index.zh.md)** 18 | 19 | 该参考文献涵盖了 Cargo 各个领域的细节. 20 | 21 | **[常见问题](faq.zh.md)** 22 | 23 | **附加:** 24 | 25 | - [术语](appendix/glossary.zh.md) 26 | - [Git Authentication](appendix/git-authentication.md) 27 | 28 | **其他文档:** 29 | 30 | - [Changelog](https://github.com/rust-lang/cargo/blob/master/CHANGELOG.md) — 31 | Detailed notes about changes in Cargo in each release. 32 | - [Rust documentation website](https://doc.rust-lang.org/) — Links to official 33 | Rust documentation and tools. 34 | 35 | [def-crate]: ./appendix/glossary.zh.md#crate '"crate" (glossary entry)' 36 | [def-package]: ./appendix/glossary.zh.md#package '"package" (glossary entry)' 37 | [def-package-manager]: ./appendix/glossary.zh.md#package-manager '"package manager" (glossary entry)' 38 | [def-package-registry]: ./appendix/glossary.zh.md#package-registry '"package registry" (glossary entry)' 39 | [rust]: https://www.rust-lang.org/ 40 | [crates.io]: https://crates.io/ 41 | [github]: https://github.com/rust-lang/cargo/tree/master/src/doc 42 | -------------------------------------------------------------------------------- /src/guide/tests.md: -------------------------------------------------------------------------------- 1 | ## Tests 2 | 3 | Cargo can run your tests with the `cargo test` command. Cargo looks for tests 4 | to run in two places: in each of your `src` files and any tests in `tests/`. 5 | Tests in your `src` files should be unit tests, and tests in `tests/` should be 6 | integration-style tests. As such, you’ll need to import your crates into 7 | the files in `tests`. 8 | 9 | Here's an example of running `cargo test` in our [package][def-package], which 10 | currently has no tests: 11 | 12 | ```console 13 | $ cargo test 14 | Compiling regex v1.5.0 (https://github.com/rust-lang/regex.git#9f9f693) 15 | Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) 16 | Running target/test/hello_world-9c2b65bbb79eabce 17 | 18 | running 0 tests 19 | 20 | test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out 21 | ``` 22 | 23 | If our package had tests, we would see more output with the correct number of 24 | tests. 25 | 26 | You can also run a specific test by passing a filter: 27 | 28 | ```console 29 | $ cargo test foo 30 | ``` 31 | 32 | This will run any test with `foo` in its name. 33 | 34 | `cargo test` runs additional checks as well. It will compile any 35 | examples you’ve included and will also test the examples in your 36 | documentation. Please see the [testing guide][testing] in the Rust 37 | documentation for more details. 38 | 39 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 40 | [testing]: ../../book/ch11-00-testing.html 41 | -------------------------------------------------------------------------------- /docs/highlight.css: -------------------------------------------------------------------------------- 1 | /* 2 | * An increased contrast highlighting scheme loosely based on the 3 | * "Base16 Atelier Dune Light" theme by Bram de Haan 4 | * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune) 5 | * Original Base16 color scheme by Chris Kempson 6 | * (https://github.com/chriskempson/base16) 7 | */ 8 | 9 | /* Comment */ 10 | .hljs-comment, 11 | .hljs-quote { 12 | color: #575757; 13 | } 14 | 15 | /* Red */ 16 | .hljs-variable, 17 | .hljs-template-variable, 18 | .hljs-attribute, 19 | .hljs-tag, 20 | .hljs-name, 21 | .hljs-regexp, 22 | .hljs-link, 23 | .hljs-name, 24 | .hljs-selector-id, 25 | .hljs-selector-class { 26 | color: #d70025; 27 | } 28 | 29 | /* Orange */ 30 | .hljs-number, 31 | .hljs-meta, 32 | .hljs-built_in, 33 | .hljs-builtin-name, 34 | .hljs-literal, 35 | .hljs-type, 36 | .hljs-params { 37 | color: #b21e00; 38 | } 39 | 40 | /* Green */ 41 | .hljs-string, 42 | .hljs-symbol, 43 | .hljs-bullet { 44 | color: #008200; 45 | } 46 | 47 | /* Blue */ 48 | .hljs-title, 49 | .hljs-section { 50 | color: #0030f2; 51 | } 52 | 53 | /* Purple */ 54 | .hljs-keyword, 55 | .hljs-selector-tag { 56 | color: #9d00ec; 57 | } 58 | 59 | .hljs { 60 | display: block; 61 | overflow-x: auto; 62 | background: #f6f7f6; 63 | color: #000; 64 | padding: 0.5em; 65 | } 66 | 67 | .hljs-emphasis { 68 | font-style: italic; 69 | } 70 | 71 | .hljs-strong { 72 | font-weight: bold; 73 | } 74 | 75 | .hljs-addition { 76 | color: #22863a; 77 | background-color: #f0fff4; 78 | } 79 | 80 | .hljs-deletion { 81 | color: #b31d28; 82 | background-color: #ffeef0; 83 | } 84 | -------------------------------------------------------------------------------- /src/getting-started/first-steps.zh.md: -------------------------------------------------------------------------------- 1 | ## Cargo 的第一步 2 | 3 | 本章节提供，cargo 命令的一些常用场景。如： 4 | 5 | 1. 生成一个新的[**_package_**][def-package] 6 | 2. 在 package 内，编译 [**_crate_**][def-crate] 7 | 3. 以及，运行程序 8 | 9 | 要使用 Cargo 启动新项目，请使用`cargo new`: 10 | 11 | ```shell 12 | $ cargo new hello_world 13 | ``` 14 | 15 | 默认我们会传递`--bin`参数，表明我们正在制作一个二进制程序: 如果我们正在创建一个库(lib)，我们就会把传递`--lib`参数。 16 | 17 | 让我们来看看 Cargo 为我们带来了什么: 18 | 19 | ```shell 20 | $ cd hello_world 21 | $ tree . 22 | . 23 | ├── Cargo.toml 24 | └── src 25 | └── main.rs 26 | 27 | 1 directory, 2 files 28 | ``` 29 | 30 | 这就是我们开始所需要的一切。首先，让我们看看`Cargo.toml`: 31 | 32 | ```toml 33 | [package] 34 | name = "hello_world" 35 | version = "0.1.0" 36 | edition = "2021" 37 | 38 | [dependencies] 39 | ``` 40 | 41 | 这被称为，**manifest**元清单，它包含了 Cargo 编译项目所需的所有元数据. 42 | 43 | 那`src/main.rs`有啥: 44 | 45 | ```rust 46 | fn main() { 47 | println!("Hello, world!"); 48 | } 49 | ``` 50 | 51 | Cargo 为我们创造了一个"hello_world"，也就是一个[**_binary crate_**][def-crate]。让我们来编译它: 52 | 53 | ```shell 54 | $ cargo build 55 | Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) 56 | ``` 57 | 58 | 然后，运行它: 59 | 60 | ```shell 61 | $ ./target/debug/hello_world 62 | Hello, world! 63 | ``` 64 | 65 | 我们也可以直接使用`cargo run`，它会自行编译，然后运行它， 一步到位: 66 | 67 | ```shell 68 | $ cargo run 69 | Fresh hello_world v0.1.0 (file:///path/to/project/hello_world) 70 | Running `target/hello_world` 71 | Hello, world! 72 | ``` 73 | 74 | ## 走得更远 75 | 76 | 有关使用 Cargo 的更多详细信息，请查看[Cargo 指南](../guide/index.zh.md) 77 | 78 | [def-crate]: ../appendix/glossary.zh.md#crate '"crate" (glossary entry)' 79 | [def-manifest]: ../appendix/glossary.zh.md#manifest '"manifest" (glossary entry)' 80 | [def-package]: ../appendix/glossary.zh.md#package '"package" (glossary entry)' 81 | -------------------------------------------------------------------------------- /src/guide/project-layout.zh.md: -------------------------------------------------------------------------------- 1 | ## 项目布局 2 | 3 | Cargo 使用文件放置惯例，以便轻松进入新的 Cargo 项目: 4 | 5 | ```text 6 | . 7 | ├── Cargo.lock 8 | ├── Cargo.toml 9 | ├── src/ 10 | │   ├── lib.rs 11 | │   ├── main.rs 12 | │   └── bin/ 13 | │ ├── named-executable.rs 14 | │      ├── another-executable.rs 15 | │      └── multi-file-executable/ 16 | │      ├── main.rs 17 | │      └── some_module.rs 18 | ├── benches/ 19 | │   ├── large-input.rs 20 | │   └── multi-file-bench/ 21 | │   ├── main.rs 22 | │   └── bench_module.rs 23 | ├── examples/ 24 | │   ├── simple.rs 25 | │   └── multi-file-example/ 26 | │   ├── main.rs 27 | │   └── ex_module.rs 28 | └── tests/ 29 | ├── some-integration-tests.rs 30 | └── multi-file-test/ 31 | ├── main.rs 32 | └── test_module.rs 33 | ``` 34 | 35 | - `Cargo.toml`和`Cargo.lock`存储在项目的根目录中. 36 | - 源代码进入`src`目录 37 | - 默认库文件是`src/lib.rs` 38 | - 默认的可执行文件是`src/main.rs` 39 | - 其他可执行文件，可以放入`src/bin/*.rs` 40 | - 集成测试进入`tests`目录 41 | - 示例进入`examples`目录 42 | - 基准进入`benches`目录 43 | 44 | 如果一个 binary, example, bench 或是集成测试由多个源文件组成，那么在`src/bin`, `examples`, `benches`, or `tests`的子目录里，放一个带有额外[_modules_][def-module] 的`main.rs`文件。执行名为目录名。 45 | 46 | 关于 Rust's 模块系统在这本书 [the book][book-modules]。 47 | 48 | 也可以看看 [配置一个 target][configuring a target] 关于手动配置 targets 的方法。 49 | 还可以看看 [自动发现 Target][Target auto-discovery] ，关于操纵 Cargo 自动推断 target 名称。 50 | 51 | [book-modules]: ../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html 52 | [configuring a target]: ../reference/cargo-targets.zh.md#configuring-a-target 53 | [def-package]: ../appendix/glossary.zh.md#package '"package" (glossary entry)' 54 | [def-module]: ../appendix/glossary.zh.md#module '"module" (glossary entry)' 55 | [target auto-discovery]: ../reference/cargo-targets.zh.md#target-auto-discovery 56 | -------------------------------------------------------------------------------- /docs/favicon.svg: -------------------------------------------------------------------------------- 1 | 2 | 7 | 21 | 22 | 23 | -------------------------------------------------------------------------------- /src/appendix/git-authentication.zh.md: -------------------------------------------------------------------------------- 1 | # Git Authentication 2 | 3 | Cargo在使用git依赖项和注册表时支持某些形式的身份验证。本附录包含一些信息，用于以与Cargo兼容的方式设置git身份验证。 4 | 5 | 如果需要其他身份验证方法，则[`net.git-fetch-with-cli`]配置值可以设置为使Cargo执行`git`用于处理获取远程存储库的可执行文件，而不是使用内置支持。这可以通过`CARGO_NET_GIT_FETCH_WITH_CLI=true`环境变量。 6 | 7 | ## HTTPS authentication 8 | 9 | HTTPS身份验证需要[`credential.helper`]机械装置有多个凭证帮助程序，您可以指定要在全局git配置文件中使用的凭证帮助程序。 10 | 11 | ```ini 12 | # ~/.gitconfig 13 | 14 | [credential] 15 | helper = store 16 | ``` 17 | 18 | Cargo不要求输入密码，因此对于大多数助手，在运行Cargo之前，您需要为助手提供初始用户名/密码。一种方法是跑步`git clone`输入用户名/密码。 19 | 20 | > **提示：**
MACOS用户可能想考虑使用OXKEY链助手。
Windows用户可能想考虑使用[GCM]帮手 21 | > 22 | > **注：**Windows用户需要确保`sh`shell在您的`PATH`。这通常在Git for Windows安装中提供。 23 | 24 | ## SSH authentication 25 | 26 | SSH身份验证需要`ssh-agent`正在运行以获取SSH密钥。确保设置了适当的环境变量(`SSH_AUTH_SOCK`在大多数类似Unix的系统上），并且添加了正确的密钥（使用`ssh-add`). 27 | 28 | Windows可以使用Pageant（部分功能）[PuTTY])或者`ssh-agent`.使用`ssh-agent`，Cargo需要使用作为Windows一部分分发的OpenSSH，因为Cargo不支持MinGW或Cygwin使用的模拟Unix域套接字。有关Windows安装的更多信息，请访问[Microsoft 29 | installation documentation]这一页[key management]有关于如何开始的说明`ssh-agent`以及添加密钥。 30 | 31 | > **注：**Cargo不支持git的简写SSH URL，比如`git@example.com:user/repo.git`.使用完整的SSH URL，如`ssh://git@example.com/user/repo.git`. 32 | > 33 | > **注：**SSH配置文件（如OpenSSH）`~/.ssh/config`)Cargo的内置SSH库不使用。应该使用更高级的需求[`net.git-fetch-with-cli`]. 34 | 35 | [`credential.helper`]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage 36 | 37 | [`net.git-fetch-with-cli`]: ../reference/config.md#netgit-fetch-with-cli 38 | 39 | [gcm]: https://github.com/microsoft/Git-Credential-Manager-Core/ 40 | 41 | [putty]: https://www.chiark.greenend.org.uk/~sgtatham/putty/ 42 | 43 | [microsoft installation documentation]: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse 44 | 45 | [key management]: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement 46 | -------------------------------------------------------------------------------- /src/index.md: -------------------------------------------------------------------------------- 1 | # The Cargo Book 2 | 3 | ![Cargo Logo](images/Cargo-Logo-Small.png) 4 | 5 | Cargo is the [Rust] [*package manager*][def-package-manager]. Cargo downloads your Rust [package][def-package]'s 6 | dependencies, compiles your packages, makes distributable packages, and uploads them to 7 | [crates.io], the Rust community’s [*package registry*][def-package-registry]. You can contribute 8 | to this book on [GitHub]. 9 | 10 | 11 | ### Sections 12 | 13 | **[Getting Started](getting-started/index.md)** 14 | 15 | To get started with Cargo, install Cargo (and Rust) and set up your first 16 | [*crate*][def-crate]. 17 | 18 | **[Cargo Guide](guide/index.md)** 19 | 20 | The guide will give you all you need to know about how to use Cargo to develop 21 | Rust packages. 22 | 23 | **[Cargo Reference](reference/index.md)** 24 | 25 | The reference covers the details of various areas of Cargo. 26 | 27 | **[Cargo Commands](commands/index.md)** 28 | 29 | The commands will let you interact with Cargo using its command-line interface. 30 | 31 | **[Frequently Asked Questions](faq.md)** 32 | 33 | **Appendices:** 34 | * [Glossary](appendix/glossary.md) 35 | * [Git Authentication](appendix/git-authentication.md) 36 | 37 | **Other Documentation:** 38 | * [Changelog](https://github.com/rust-lang/cargo/blob/master/CHANGELOG.md) — 39 | Detailed notes about changes in Cargo in each release. 40 | * [Rust documentation website](https://doc.rust-lang.org/) — Links to official 41 | Rust documentation and tools. 42 | 43 | [def-crate]: ./appendix/glossary.md#crate '"crate" (glossary entry)' 44 | [def-package]: ./appendix/glossary.md#package '"package" (glossary entry)' 45 | [def-package-manager]: ./appendix/glossary.md#package-manager '"package manager" (glossary entry)' 46 | [def-package-registry]: ./appendix/glossary.md#package-registry '"package registry" (glossary entry)' 47 | [rust]: https://www.rust-lang.org/ 48 | [crates.io]: https://crates.io/ 49 | [GitHub]: https://github.com/rust-lang/cargo/tree/master/src/doc 50 | -------------------------------------------------------------------------------- /contrib/src/tests/running.md: -------------------------------------------------------------------------------- 1 | # Running Tests 2 | 3 | Using `cargo test` is usually sufficient for running the full test suite. This 4 | can take a few minutes, so you may want to use more targeted flags to pick the 5 | specific test you want to run, such as `cargo test --test testsuite 6 | -- check::check_success`. 7 | 8 | ## Running nightly tests 9 | 10 | Some tests only run on the nightly toolchain, and will be ignored on other 11 | channels. It is recommended that you run tests with both nightly and stable to 12 | ensure everything is working as expected. 13 | 14 | Some of the nightly tests require the `rustc-dev` and `llvm-tools-preview` 15 | rustup components installed. These components include the compiler as a 16 | library. This may already be installed with your nightly toolchain, but if it 17 | isn't, run `rustup component add rustc-dev llvm-tools-preview 18 | --toolchain=nightly`. 19 | 20 | ## Running cross tests 21 | 22 | Some tests exercise cross compiling to a different target. This will require 23 | you to install the appropriate target. This typically is the 32-bit target of 24 | your host platform. For example, if your host is a 64-bit 25 | `x86_64-unknown-linux-gnu`, then you should install the 32-bit target with 26 | `rustup target add i686-unknown-linux-gnu`. If you don't have the alternate 27 | target installed, there should be an error message telling you what to do. You 28 | may also need to install additional tools for the target. For example, on Ubuntu 29 | you should install the `gcc-multilib` package. 30 | 31 | If you can't install an alternate target, you can set the 32 | `CFG_DISABLE_CROSS_TESTS=1` environment variable to disable these tests. The 33 | Windows cross tests only support the MSVC toolchain. 34 | 35 | ## Running build-std tests 36 | 37 | The `build-std` tests are disabled by default, but you can run them by setting 38 | the `CARGO_RUN_BUILD_STD_TESTS=1` environment variable and running `cargo test 39 | --test build-std`. This requires the nightly channel, and also requires the 40 | `rust-src` component installed with `rustup component add rust-src 41 | --toolchain=nightly`. 42 | -------------------------------------------------------------------------------- /src/guide/creating-a-new-project.zh.md: -------------------------------------------------------------------------------- 1 | ## 创建一个新项目 2 | 3 | 要使用 Cargo 启动 新[package][def-package]，请使用`cargo new`: 4 | 5 | ```shell 6 | $ cargo new hello_world --bin 7 | ``` 8 | 9 | 我们传递`--bin`，是因为我们正在制作一个二进制程序(默认): 如果我们正在创建一个库(lib)，我们就会把传递`--lib`。默认情况下，这个目录会初始化为一个新的`git`存储库，如果您不希望它这样做，请传递`--vcs none`。 10 | 11 | 让我们来看看 Cargo 为我们带来了什么: 12 | 13 | ```shell 14 | $ cd hello_world 15 | $ tree . 16 | . 17 | ├── Cargo.toml 18 | └── src 19 | └── main.rs 20 | 21 | 1 directory, 2 files 22 | ``` 23 | 24 | 这就是我们开始所需要的一切首。先让我们看看`Cargo.toml`: 25 | 26 | ```toml 27 | [package] 28 | name = "hello_world" 29 | version = "0.1.0" 30 | authors = ["Your Name "] 31 | edition = "2018" 32 | 33 | [dependencies] 34 | ``` 35 | 36 | 这被称为一个**manifest**元清单，它包含了 Cargo 编译项目所需的所有元数据，它是 37 | [TOML] 格式的文件。 38 | 39 | 那`src/main.rs`有啥: 40 | 41 | ```rust 42 | fn main() { 43 | println!("Hello, world!"); 44 | } 45 | ``` 46 | 47 | Cargo 为我们创造了一个"hello_world"，一个[*binary crate*][def-crate]。我们来编译它: 48 | 49 | ```shell 50 | $ cargo build 51 | Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) 52 | ``` 53 | 54 | 然后，运行它: 55 | 56 | ```shell 57 | $ ./target/debug/hello_world 58 | Hello, world! 59 | ``` 60 | 61 | 我们也可以直接使用`cargo run`，它会自行编译，然后运行它, 一步到位(如果，你看不到`Compiling`标识的输出行，说明你并没有更改那些项): 62 | 63 | ```shell 64 | $ cargo run 65 | Fresh hello_world v0.1.0 (file:///path/to/project/hello_world) 66 | Running `target/hello_world` 67 | Hello, world! 68 | ``` 69 | 70 | 这个`Cargo.lock`文件啊，是包含我们的依赖项的有关信息(即便还没有依赖)，其内容看起来可不是很有趣啊。再有就是`target`目录包含所有构建产品(二进制文件..)，并且，可以看出，Cargo 默认生成调试(debug)版本。您可以使用`cargo build --release`，这会在开启优化的情况下，编译文件: 71 | 72 | ```shell 73 | $ cargo build --release 74 | Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) 75 | ``` 76 | 77 | `cargo build --release`将结果二进制文件放入`target/release`，而不再是`target/debug`目录. 78 | 79 | 调试模式的编译是开发的默认设置 - 编译时间较短，因为编译器不进行优化，但代码运行速度较慢。发布(release)模式编译需要更长时间，但代码运行速度更快. 80 | 81 | [toml]: https://toml.io/ 82 | [def-crate]: ../appendix/glossary.zh.md#crate '"crate" (glossary entry)' 83 | [def-manifest]: ../appendix/glossary.zh.md#manifest '"manifest" (glossary entry)' 84 | [def-package]: ../appendix/glossary.zh.md#package '"package" (glossary entry)' 85 | -------------------------------------------------------------------------------- /src/getting-started/first-steps.md: -------------------------------------------------------------------------------- 1 | ## First Steps with Cargo 2 | 3 | This section provides a quick sense for the `cargo` command line tool. We 4 | demonstrate its ability to generate a new [***package***][def-package] for us, 5 | its ability to compile the [***crate***][def-crate] within the package, and 6 | its ability to run the resulting program. 7 | 8 | To start a new package with Cargo, use `cargo new`: 9 | 10 | ```console 11 | $ cargo new hello_world 12 | ``` 13 | 14 | Cargo defaults to `--bin` to make a binary program. To make a library, we 15 | would pass `--lib`, instead. 16 | 17 | Let’s check out what Cargo has generated for us: 18 | 19 | ```console 20 | $ cd hello_world 21 | $ tree . 22 | . 23 | ├── Cargo.toml 24 | └── src 25 | └── main.rs 26 | 27 | 1 directory, 2 files 28 | ``` 29 | 30 | This is all we need to get started. First, let’s check out `Cargo.toml`: 31 | 32 | ```toml 33 | [package] 34 | name = "hello_world" 35 | version = "0.1.0" 36 | edition = "2021" 37 | 38 | [dependencies] 39 | ``` 40 | 41 | This is called a [***manifest***][def-manifest], and it contains all of the 42 | metadata that Cargo needs to compile your package. 43 | 44 | Here’s what’s in `src/main.rs`: 45 | 46 | ```rust 47 | fn main() { 48 | println!("Hello, world!"); 49 | } 50 | ``` 51 | 52 | Cargo generated a “hello world” program for us, otherwise known as a 53 | [***binary crate***][def-crate]. Let’s compile it: 54 | 55 | ```console 56 | $ cargo build 57 | Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) 58 | ``` 59 | 60 | And then run it: 61 | 62 | ```console 63 | $ ./target/debug/hello_world 64 | Hello, world! 65 | ``` 66 | 67 | We can also use `cargo run` to compile and then run it, all in one step: 68 | 69 | ```console 70 | $ cargo run 71 | Fresh hello_world v0.1.0 (file:///path/to/package/hello_world) 72 | Running `target/hello_world` 73 | Hello, world! 74 | ``` 75 | 76 | ### Going further 77 | 78 | For more details on using Cargo, check out the [Cargo Guide](../guide/index.md) 79 | 80 | [def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' 81 | [def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' 82 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 83 | -------------------------------------------------------------------------------- /src/reference/external-tools.zh.md: -------------------------------------------------------------------------------- 1 | ## External tools 2 | 3 | 外部工具 4 | 5 | Cargo 的目标之一是与第三方工具(如 IDE 和其他构建系统)的简单集成。为了简化集成，Cargo 有几个设施: 6 | 7 | - 一个`cargo metadata`命令，以 JSON 格式输出包结构和依赖关系信息， 8 | 9 | - 一个`--message-format`标志，输出有关特定构建的信息，以及 10 | 11 | - 支持自定义子命令. 12 | 13 | ### Information about package structure 14 | 15 | 包结构的资料 16 | 17 | 您可以使用`cargo metadata`命令，以获取有关包结构和依赖关系的信息。命令的输出如下所示: 18 | 19 | ```text 20 | { 21 | // Integer 版本格式数字. 22 | "version": integer, 23 | 24 | // 工作区包的列表, 包括 依赖项. 25 | "packages": [ 26 | { 27 | // 包 识别id 队列. 28 | "id": PackageId, 29 | 30 | "name": string, 31 | 32 | "version": string, 33 | 34 | "source": SourceId, 35 | 36 | // 确认依赖的一个列表, 可看 `resolve` 字段中的真实依赖. 37 | "dependencies": [ Dependency ], 38 | 39 | "targets: [ Target ], 40 | 41 | // Cargo.toml 路径 42 | "manifest_path": string, 43 | } 44 | ], 45 | 46 | "workspace_members": [ PackageId ], 47 | 48 | // 依赖 关系图. 49 | "resolve": { 50 | "nodes": [ 51 | { 52 | "id": PackageId, 53 | "dependencies": [ PackageId ] 54 | } 55 | ] 56 | } 57 | } 58 | ``` 59 | 60 | 格式稳定且有版本化。调用`cargo metadata`时，你应该通过`--format-version`明确标记，以避免向前不兼容的危险。 61 | 62 | 如果你正在使用 Rust，这有个[cargo_metadata]箱. 63 | 64 | [cargo_metadata]: https://crates.io/crates/cargo_metadata 65 | 66 | ### Information about build 67 | 68 | 关于构建的资料 69 | 70 | 传递`--message-format=json`给，Cargo， 将在构建期间输出以下信息: 71 | 72 | - 编译器错误和警告， 73 | 74 | - 制作的工件， 75 | 76 | - 构建脚本的结果(例如，本机依赖项). 77 | 78 | 输出以每行格式的 JSON 对象转到 stdout。`reason`字段区分不同类型的消息. 79 | 80 | 有关 Makefile 兼容格式的依赖关系的信息存储在工件旁的`.d`文件中。 81 | 82 | ### Custom subcommands 83 | 84 | 自定义的子命令 85 | 86 | Cargo 设计为，可以使用新的子命令进行扩展，而无需修改 Cargo 本身。这是通过转化一个 cargo `(?[^ ]+)`的命令调用，变化为调用外部工具`cargo-${command}`来实现的。外部工具必须存在于用户其中一个`$PATH`目录中. 87 | 88 | 当 Cargo 调用自定义子命令时，子命令的第一个参数将像往常一样是自定义子命令的文件名。第二个参数将是子命令名称本身。例如，在调用`cargo-${command}`时，第二个参数是`${command}`。命令行上的其他所有参数将保持不变. 89 | 90 | Cargo 还可以用`cargo help ${command}`显示自定义子命令的帮助输出。Cargo 假定子命令将在第三个参数出现时，打印帮助消息`--help`.所以，`cargo help ${command}`会调用`cargo-${command} ${command} --help`. 91 | 92 | 自定义子命令可以使用`CARGO`环境变量回调 Cargo。或者，它可以链接到作为一个库的`cargo`箱，但这种方法有缺点: 93 | 94 | - Cargo 作为库是不稳定的:API 可能会更改，但不会弃用 95 | 96 | - 链接的 Cargo 库的版本可能与 Cargo 二进制文件不同 97 | -------------------------------------------------------------------------------- /docs/tomorrow-night.css: -------------------------------------------------------------------------------- 1 | /* Tomorrow Night Theme */ 2 | /* http://jmblog.github.com/color-themes-for-google-code-highlightjs */ 3 | /* Original theme - https://github.com/chriskempson/tomorrow-theme */ 4 | /* http://jmblog.github.com/color-themes-for-google-code-highlightjs */ 5 | 6 | /* Tomorrow Comment */ 7 | .hljs-comment { 8 | color: #969896; 9 | } 10 | 11 | /* Tomorrow Red */ 12 | .hljs-variable, 13 | .hljs-attribute, 14 | .hljs-tag, 15 | .hljs-regexp, 16 | .ruby .hljs-constant, 17 | .xml .hljs-tag .hljs-title, 18 | .xml .hljs-pi, 19 | .xml .hljs-doctype, 20 | .html .hljs-doctype, 21 | .css .hljs-id, 22 | .css .hljs-class, 23 | .css .hljs-pseudo { 24 | color: #cc6666; 25 | } 26 | 27 | /* Tomorrow Orange */ 28 | .hljs-number, 29 | .hljs-preprocessor, 30 | .hljs-pragma, 31 | .hljs-built_in, 32 | .hljs-literal, 33 | .hljs-params, 34 | .hljs-constant { 35 | color: #de935f; 36 | } 37 | 38 | /* Tomorrow Yellow */ 39 | .ruby .hljs-class .hljs-title, 40 | .css .hljs-rule .hljs-attribute { 41 | color: #f0c674; 42 | } 43 | 44 | /* Tomorrow Green */ 45 | .hljs-string, 46 | .hljs-value, 47 | .hljs-inheritance, 48 | .hljs-header, 49 | .hljs-name, 50 | .ruby .hljs-symbol, 51 | .xml .hljs-cdata { 52 | color: #b5bd68; 53 | } 54 | 55 | /* Tomorrow Aqua */ 56 | .hljs-title, 57 | .css .hljs-hexcolor { 58 | color: #8abeb7; 59 | } 60 | 61 | /* Tomorrow Blue */ 62 | .hljs-function, 63 | .python .hljs-decorator, 64 | .python .hljs-title, 65 | .ruby .hljs-function .hljs-title, 66 | .ruby .hljs-title .hljs-keyword, 67 | .perl .hljs-sub, 68 | .javascript .hljs-title, 69 | .coffeescript .hljs-title { 70 | color: #81a2be; 71 | } 72 | 73 | /* Tomorrow Purple */ 74 | .hljs-keyword, 75 | .javascript .hljs-function { 76 | color: #b294bb; 77 | } 78 | 79 | .hljs { 80 | display: block; 81 | overflow-x: auto; 82 | background: #1d1f21; 83 | color: #c5c8c6; 84 | padding: 0.5em; 85 | -webkit-text-size-adjust: none; 86 | } 87 | 88 | .coffeescript .javascript, 89 | .javascript .xml, 90 | .tex .hljs-formula, 91 | .xml .javascript, 92 | .xml .vbscript, 93 | .xml .css, 94 | .xml .hljs-cdata { 95 | opacity: 0.5; 96 | } 97 | 98 | .hljs-addition { 99 | color: #718c00; 100 | } 101 | 102 | .hljs-deletion { 103 | color: #c82829; 104 | } 105 | -------------------------------------------------------------------------------- /src/guide/project-layout.md: -------------------------------------------------------------------------------- 1 | ## Package Layout 2 | 3 | Cargo uses conventions for file placement to make it easy to dive into a new 4 | Cargo [package][def-package]: 5 | 6 | ```text 7 | . 8 | ├── Cargo.lock 9 | ├── Cargo.toml 10 | ├── src/ 11 | │   ├── lib.rs 12 | │   ├── main.rs 13 | │   └── bin/ 14 | │ ├── named-executable.rs 15 | │      ├── another-executable.rs 16 | │      └── multi-file-executable/ 17 | │      ├── main.rs 18 | │      └── some_module.rs 19 | ├── benches/ 20 | │   ├── large-input.rs 21 | │   └── multi-file-bench/ 22 | │   ├── main.rs 23 | │   └── bench_module.rs 24 | ├── examples/ 25 | │   ├── simple.rs 26 | │   └── multi-file-example/ 27 | │   ├── main.rs 28 | │   └── ex_module.rs 29 | └── tests/ 30 | ├── some-integration-tests.rs 31 | └── multi-file-test/ 32 | ├── main.rs 33 | └── test_module.rs 34 | ``` 35 | 36 | * `Cargo.toml` and `Cargo.lock` are stored in the root of your package (*package 37 | root*). 38 | * Source code goes in the `src` directory. 39 | * The default library file is `src/lib.rs`. 40 | * The default executable file is `src/main.rs`. 41 | * Other executables can be placed in `src/bin/`. 42 | * Benchmarks go in the `benches` directory. 43 | * Examples go in the `examples` directory. 44 | * Integration tests go in the `tests` directory. 45 | 46 | If a binary, example, bench, or integration test consists of multiple source 47 | files, place a `main.rs` file along with the extra [*modules*][def-module] 48 | within a subdirectory of the `src/bin`, `examples`, `benches`, or `tests` 49 | directory. The name of the executable will be the directory name. 50 | 51 | You can learn more about Rust's module system in [the book][book-modules]. 52 | 53 | See [Configuring a target] for more details on manually configuring targets. 54 | See [Target auto-discovery] for more information on controlling how Cargo 55 | automatically infers target names. 56 | 57 | [book-modules]: ../../book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html 58 | [Configuring a target]: ../reference/cargo-targets.md#configuring-a-target 59 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 60 | [def-module]: ../appendix/glossary.md#module '"module" (glossary entry)' 61 | [Target auto-discovery]: ../reference/cargo-targets.md#target-auto-discovery 62 | -------------------------------------------------------------------------------- /src/guide/dependencies.zh.md: -------------------------------------------------------------------------------- 1 | ## 从 crates.io 添加依赖项 2 | 3 | [crates.io]是 Rust 社区的中央[_package registry_][def-package-registry]，用作发现和下载[packages][def-package] 的位置。`cargo`默认配置为，使用它来查找请求的包. 4 | 5 | 获取托管在[crates.io]的依赖'库'，将它添加到您的`Cargo.toml`. 6 | 7 | [crates.io]: https://crates.io/ 8 | 9 | ### 添加依赖项 10 | 11 | 如果你的`Cargo.toml`，还没有`[dependencies]`部分，添加它，然后列出您要使用的[crate][def-crate]名称和版本。这个例子增加了一个`time`箱子依赖: 12 | 13 | ```toml 14 | [dependencies] 15 | time = "0.1.12" 16 | ``` 17 | 18 | 版本字符串是[SemVer]版本要求。该[指定依赖项](../reference/specifying-dependencies.zh.md)文档 提供了有关此处选项的更多信息. 19 | 20 | [semver]: https://semver.org 21 | 22 | 如果我们还想添加一个`regex`箱子依赖，我们不需要为每个箱子都添加`[dependencies]`。下面就是你的`Cargo.toml`文件整体，看起来像依赖于`time`和`regex`箱: 23 | 24 | ```toml 25 | [package] 26 | name = "hello_world" 27 | version = "0.1.0" 28 | edition = "2021" 29 | 30 | [dependencies] 31 | time = "0.1.12" 32 | regex = "0.1.41" 33 | ``` 34 | 35 | 重新运行`cargo build`，Cargo 将获取新的依赖项及其所有依赖项，将它们全部编译，然后更新`Cargo.lock`: 36 | 37 | ```shell 38 | $ cargo build 39 | Updating registry `https://github.com/rust-lang/crates.io-index` 40 | Downloading memchr v0.1.5 41 | Downloading libc v0.1.10 42 | Downloading regex-syntax v0.2.1 43 | Downloading memchr v0.1.5 44 | Downloading aho-corasick v0.3.0 45 | Downloading regex v0.1.41 46 | Compiling memchr v0.1.5 47 | Compiling libc v0.1.10 48 | Compiling regex-syntax v0.2.1 49 | Compiling memchr v0.1.5 50 | Compiling aho-corasick v0.3.0 51 | Compiling regex v0.1.41 52 | Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) 53 | ``` 54 | 55 | 我们的`Cargo.lock`包含有关，我们使用的所有这些依赖项的哪个版本的确实信息. 56 | 57 | 现在，如果`regex`在[crates.io]上更新了，在我们选择`cargo update`之前，我们仍会使用相同的版本进行构建. 58 | 59 | 你现在可以在`main.rs`，使用`regex`箱了。 60 | 61 | ```rust 62 | extern crate regex; 63 | 64 | use regex::Regex; 65 | 66 | fn main() { 67 | let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap(); 68 | println!("Did our date match? {}", re.is_match("2014-01-01")); 69 | } 70 | ``` 71 | 72 | 运行它，将显示: 73 | 74 | ```shell 75 | $ cargo run 76 | Running `target/hello_world` 77 | Did our date match? true 78 | ``` 79 | 80 | [def-crate]: ../appendix/glossary.zh.md#crate '"crate" (glossary entry)' 81 | [def-package]: ../appendix/glossary.zh.md#package '"package" (glossary entry)' 82 | [def-package-registry]: ../appendix/glossary.zh.md#package-registry '"package-registry" (glossary entry)' 83 | -------------------------------------------------------------------------------- /src/guide/cargo-toml-vs-cargo-lock.zh.md: -------------------------------------------------------------------------------- 1 | ## Cargo.toml 与 Cargo.lock 2 | 3 | `Cargo.toml`和`Cargo.lock`各有其目的。在我们谈论它们之前，这是一个总结: 4 | 5 | - `Cargo.toml`是从广义上描述你的依赖，并由你编写. 6 | - `Cargo.lock`包含有关您的依赖项的确切信息。它由 Cargo 维护，不应手动编辑. 7 | 8 | 如果您正在构建，其他项目要依赖的库，请将`Cargo.lock`放置在你的`.gitignore`。如果您正在构建可执行文件，如命令行工具或应用程序，请检查`Cargo.lock`位于`git`管理下。如果你对这是为什么感到好奇，请参阅["为什么二进制文件在版本控制系统中有`Cargo.lock`，而库没有?" - FAQ ](../faq.zh.md#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). 9 | 10 | 让我们再挖掘一下. 11 | 12 | `Cargo.toml`是一个**manifest(清单)**，我们可以在其中指定一系列关于我们项目的不同元数据的文件。例如，我们可以说我们依赖于另一个项目: 13 | 14 | ```toml 15 | [package] 16 | name = "hello_world" 17 | version = "0.1.0" 18 | authors = ["Your Name "] 19 | 20 | [dependencies] 21 | rand = { git = "https://github.com/rust-lang-nursery/rand.git" } 22 | ``` 23 | 24 | 这个项目有一个依赖关系`rand`箱。在这种情况下，我们已经说过，我们依赖于 GitHub 上的特定 Git 存储库。由于我们尚未指定任何其他信息，因此 Cargo 假定我们打算使用最新提交的`master`分支构建我们的项目。 25 | 26 | 听起来不错? 嗯，但有一个问题: 如果你今天构建这个项目，然后你发送一份副本给我，我明天构建这个项目，可能会发生一些不好的事情。因在此期间，可能会有更多的`rand`提交，我的构建将包括新的提交，而你的不会。因此，我们会得到不同的构建。这很糟糕，因为我们需要可重复的构建. 27 | 28 | 我们可以通过放置一个`rev`来解决这个问题，写入我们`Cargo.toml`: 29 | 30 | ```toml 31 | [dependencies] 32 | rand = { git = "https://github.com/rust-lang-nursery/rand.git", rev = "9f35b8e" } 33 | ``` 34 | 35 | 现在我们的构建将是相同的。但是有一个很大的缺点:现在我们每次想要更新库时，都必须手动考虑 SHA-1。这既乏味又容易出错. 36 | 37 | 那现在`Cargo.lock`登场了。由于它的存在，我们不需要手动跟踪确切的修订版本: Cargo 将为我们做。当我们有这样的清单时: 38 | 39 | ```toml 40 | [package] 41 | name = "hello_world" 42 | version = "0.1.0" 43 | authors = ["Your Name "] 44 | 45 | [dependencies] 46 | rand = { git = "https://github.com/rust-lang-nursery/rand.git" } 47 | ``` 48 | 49 | Cargo 将采取最新的提交，并在我们第一次构建时，将这些信息写入我们的`Cargo.lock`。该文件将如下所示: 50 | 51 | ```toml 52 | [root] 53 | name = "hello_world" 54 | version = "0.1.0" 55 | dependencies = [ 56 | "rand 0.1.0 (git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9)"， 57 | ] 58 | 59 | [[package]] 60 | name = "rand" 61 | version = "0.1.0" 62 | source = "git+https://github.com/rust-lang-nursery/rand.git#9f35b8e439eeedd60b9414c58f389bdc6a3284f9" 63 | ``` 64 | 65 | 你可以看到这里有更多的信息，包括我们用来构建的确切修订版本。现在，当您将项目交给其他人时，他们将使用完全相同的 SHA，即使我们没有在我们的项目`Cargo.toml`中指定它. 66 | 67 | 当我们准备选择，更新库的版本时，Cargo 会自动重新计算依赖关系，并为我们更新内容: 68 | 69 | ```shell 70 | $ cargo update # updates all dependencies 71 | $ cargo update -p rand # updates just “rand” 72 | ``` 73 | 74 | 这将写出一个新的`Cargo.lock`与新版本信息。请注意`cargo update`参数，实际上会是是一个[包 ID 规范](../reference/pkgid-spec.zh.md)，和`rand`只是一个简短的规范. 75 | -------------------------------------------------------------------------------- /src/guide/cargo-home.zh.md: -------------------------------------------------------------------------------- 1 | ## Cargo Home 2 | 3 | The "Cargo home" 的作用，就是作为下载和源代码的缓存位置。 4 | 当构建一个 [crate][def-crate] 的时候, Cargo 会将下载的 依赖项，存储到 Cargo home. 5 | 通过 `CARGO_HOME` [environmental variable][env] 设置。 6 | 如果有需要，官方提供 [home](https://crates.io/crates/home) 箱子，获取到位置. 7 | 默认情况下，位置是 `$HOME/.cargo/`。 8 | 9 | 号外， Cargo home 内部结构尚未稳定，留意留意。 10 | 11 | The Cargo home 由以下部分组成： 12 | 13 | ## Files: 14 | 15 | - `config.toml` 16 | Cargo's 全局配置文件，参考书上会更详细点 [config entry][config]. 17 | 18 | - `credentials.toml` 19 | 来自[`cargo login`] 的私有登录证书，为了登录 [registry][def-registry]. 20 | 21 | - `.crates.toml`, `.crates2.json` 22 | 这些隐藏的文件包含 [package][def-package] 信息 —— 通过[`cargo install`]下载的。这文件不要手动修改。 23 | 24 | ## 目录: 25 | 26 | - `bin` 27 | 通过 [`cargo install`] or [`rustup`](https://rust-lang.github.io/rustup/)下载，箱子的可执行文件。 28 | 为了能够访问到这些文件，请将这个目录路径添加到`$PATH`环境变量。 29 | 30 | - `git` 31 | Git sources are stored here: 32 | 33 | - `git/db` 34 | 当一个箱子依赖一个 git repository, Cargo clones the repo 到这个目录；需要时则更新。 35 | 36 | - `git/checkouts` 37 | 这里就是放着 `git/db` 里面，git repo 具体的 commit。 38 | 它给编译器供货。 39 | 同一个 git 存储库，不同 commit 的多个 checkout，是可能的 40 | 41 | - `registry` 42 | 箱子来源的包和元信息 (such as [crates.io](https://crates.io/)) 会在这里. 43 | 44 | - `registry/index` 45 | 是一个git repo，它包含一个来源所有可用箱子的元信息 (versions, dependencies etc)。 46 | 47 | - `registry/cache` 48 | 下载的依赖项就会存储在这里。箱子会被压缩成 gzip 格式，而后缀名是 `.crate`。 49 | 50 | - `registry/src` 51 | 自然，如果一个 `.crate` 是被需要的, 就会解压缩，放到 `registry/src`，让`rustc`能够找到`.rs`文件 52 | 53 | ## Caching the Cargo home in CI 54 | 55 | 避免重复下载，所有的箱子依赖，在持续集成中，你可以缓存 `$CARGO_HOME` 目录。 56 | 然而，缓存整个目录非常低效率，因为它会包含两遍的下载文件。 57 | 比如：使用 `serde 1.0.92`，再缓存整个 `$CARGO_HOME`，那么实际上，我们是缓存了源代码两次：`registry/cache` 的 `serde-1.0.92.crate` ， 和`registry/src`的 `.rs` 。 58 | 自然，重复执行构建步骤，会让 CI 服务器花上些事件。 59 | 60 | 所以答案是，只要缓存下面的就好： 61 | 62 | - `bin/` 63 | - `registry/index/` 64 | - `registry/cache/` 65 | - `git/db/` 66 | 67 | ## Vendoring all dependencies of a project 68 | 69 | See the [`cargo vendor`] subcommand. 70 | 71 | ## Clearing the cache 72 | 73 | 理论上，你可以对缓存执行许多操作，但 74 | 75 | 最好使用 [cargo-cache](https://crates.io/crates/cargo-cache)，它提供简单的命令工具，清除缓存中的所选项，或展示大小。 76 | 77 | [`cargo install`]: ../commands/cargo-install.md 78 | [`cargo login`]: ../commands/cargo-login.md 79 | [`cargo vendor`]: ../commands/cargo-vendor.md 80 | [config]: ../reference/config.md 81 | [def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' 82 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 83 | [def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)' 84 | [env]: ../reference/environment-variables.md 85 | -------------------------------------------------------------------------------- /contrib/src/architecture/compilation.md: -------------------------------------------------------------------------------- 1 | # Compilation 2 | 3 | The [`Unit`] is the primary data structure representing a single execution of 4 | the compiler. It (mostly) contains all the information needed to determine 5 | which flags to pass to the compiler. 6 | 7 | The entry to the compilation process is located in the [`cargo_compile`] 8 | module. The compilation can be conceptually broken into these steps: 9 | 10 | 1. Perform dependency resolution (see [the resolution chapter]). 11 | 2. Generate the root `Unit`s, the things the user requested to compile on the 12 | command-line. This is done in [`generate_targets`]. 13 | 3. Starting from the root `Unit`s, generate the [`UnitGraph`] by walking the 14 | dependency graph from the resolver. The `UnitGraph` contains all of the 15 | `Unit` structs, and information about the dependency relationships between 16 | units. This is done in the [`unit_dependencies`] module. 17 | 4. Construct the [`BuildContext`] with all of the information collected so 18 | far. This is the end of the "front end" of compilation. 19 | 5. Create a [`Context`], a large, mutable data structure that coordinates the 20 | compilation process. 21 | 6. The [`Context`] will create a [`JobQueue`], a data structure that tracks 22 | which units need to be built. 23 | 7. [`drain_the_queue`] does the compilation process. This is the only point in 24 | Cargo that currently uses threads. 25 | 8. The result of the compilation is stored in the [`Compilation`] struct. This 26 | can be used for various things, such as running tests after the compilation 27 | has finished. 28 | 29 | [`cargo_compile`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/cargo_compile.rs 30 | [`generate_targets`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/ops/cargo_compile.rs#L725-L739 31 | [`UnitGraph`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_graph.rs 32 | [the resolution chapter]: packages.md 33 | [`Unit`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit.rs 34 | [`unit_dependencies`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/unit_dependencies.rs 35 | [`BuildContext`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/build_context/mod.rs 36 | [`Context`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/context/mod.rs 37 | [`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue.rs 38 | [`drain_the_queue`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/core/compiler/job_queue.rs#L623-L634 39 | [`Compilation`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/compilation.rs 40 | -------------------------------------------------------------------------------- /src/guide/creating-a-new-project.md: -------------------------------------------------------------------------------- 1 | ## Creating a New Package 2 | 3 | To start a new [package][def-package] with Cargo, use `cargo new`: 4 | 5 | ```console 6 | $ cargo new hello_world --bin 7 | ``` 8 | 9 | We’re passing `--bin` because we’re making a binary program: if we 10 | were making a library, we’d pass `--lib`. This also initializes a new `git` 11 | repository by default. If you don't want it to do that, pass `--vcs none`. 12 | 13 | Let’s check out what Cargo has generated for us: 14 | 15 | ```console 16 | $ cd hello_world 17 | $ tree . 18 | . 19 | ├── Cargo.toml 20 | └── src 21 | └── main.rs 22 | 23 | 1 directory, 2 files 24 | ``` 25 | 26 | Let’s take a closer look at `Cargo.toml`: 27 | 28 | ```toml 29 | [package] 30 | name = "hello_world" 31 | version = "0.1.0" 32 | edition = "2021" 33 | 34 | [dependencies] 35 | 36 | ``` 37 | 38 | This is called a [***manifest***][def-manifest], and it contains all of the 39 | metadata that Cargo needs to compile your package. This file is written in the 40 | [TOML] format (pronounced /tɑməl/). 41 | 42 | Here’s what’s in `src/main.rs`: 43 | 44 | ```rust 45 | fn main() { 46 | println!("Hello, world!"); 47 | } 48 | ``` 49 | 50 | Cargo generated a “hello world” program for us, otherwise known as a 51 | [*binary crate*][def-crate]. Let’s compile it: 52 | 53 | ```console 54 | $ cargo build 55 | Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) 56 | ``` 57 | 58 | And then run it: 59 | 60 | ```console 61 | $ ./target/debug/hello_world 62 | Hello, world! 63 | ``` 64 | 65 | We can also use `cargo run` to compile and then run it, all in one step (You 66 | won't see the `Compiling` line if you have not made any changes since you last 67 | compiled): 68 | 69 | ```console 70 | $ cargo run 71 | Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) 72 | Running `target/debug/hello_world` 73 | Hello, world! 74 | ``` 75 | 76 | You’ll now notice a new file, `Cargo.lock`. It contains information about our 77 | dependencies. Since we don’t have any yet, it’s not very interesting. 78 | 79 | Once you’re ready for release, you can use `cargo build --release` to compile 80 | your files with optimizations turned on: 81 | 82 | ```console 83 | $ cargo build --release 84 | Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) 85 | ``` 86 | 87 | `cargo build --release` puts the resulting binary in `target/release` instead of 88 | `target/debug`. 89 | 90 | Compiling in debug mode is the default for development. Compilation time is 91 | shorter since the compiler doesn't do optimizations, but the code will run 92 | slower. Release mode takes longer to compile, but the code will run faster. 93 | 94 | [TOML]: https://toml.io/ 95 | [def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' 96 | [def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' 97 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 98 | -------------------------------------------------------------------------------- /en.md: -------------------------------------------------------------------------------- 1 | # Cargo 2 | 3 | Cargo downloads your Rust project’s dependencies and compiles your project. 4 | 5 | Learn more at https://doc.rust-lang.org/cargo/ 6 | 7 | ## Code Status 8 | 9 | [![Build Status](https://dev.azure.com/rust-lang/cargo/_apis/build/status/rust-lang.cargo?branchName=auto-cargo)](https://dev.azure.com/rust-lang/cargo/_build?definitionId=18) 10 | 11 | Code documentation: https://docs.rs/cargo/ 12 | 13 | ## Installing Cargo 14 | 15 | Cargo is distributed by default with Rust, so if you've got `rustc` installed 16 | locally you probably also have `cargo` installed locally. 17 | 18 | ## Compiling from Source 19 | 20 | Cargo requires the following tools and packages to build: 21 | 22 | * `git` 23 | * `curl` (on Unix) 24 | * `pkg-config` (on Unix, used to figure out the `libssl` headers/libraries) 25 | * OpenSSL headers (only for Unix, this is the `libssl-dev` package on ubuntu) 26 | * `cargo` and `rustc` 27 | 28 | First, you'll want to check out this repository 29 | 30 | ``` 31 | git clone https://github.com/rust-lang/cargo 32 | cd cargo 33 | ``` 34 | 35 | With `cargo` already installed, you can simply run: 36 | 37 | ``` 38 | cargo build --release 39 | ``` 40 | 41 | ## Adding new subcommands to Cargo 42 | 43 | Cargo is designed to be extensible with new subcommands without having to modify 44 | Cargo itself. See [the Wiki page][third-party-subcommands] for more details and 45 | a list of known community-developed subcommands. 46 | 47 | [third-party-subcommands]: https://github.com/rust-lang/cargo/wiki/Third-party-cargo-subcommands 48 | 49 | 50 | ## Releases 51 | 52 | Cargo releases coincide with Rust releases. 53 | High level release notes are available as part of [Rust's release notes][rel]. 54 | Detailed release notes are available in this repo at [CHANGELOG.md]. 55 | 56 | [rel]: https://github.com/rust-lang/rust/blob/master/RELEASES.md 57 | [CHANGELOG.md]: CHANGELOG.md 58 | 59 | ## Reporting issues 60 | 61 | Found a bug? We'd love to know about it! 62 | 63 | Please report all issues on the GitHub [issue tracker][issues]. 64 | 65 | [issues]: https://github.com/rust-lang/cargo/issues 66 | 67 | ## Contributing 68 | 69 | See the **[Cargo Contributor Guide]** for a complete introduction 70 | to contributing to Cargo. 71 | 72 | [Cargo Contributor Guide]: https://rust-lang.github.io/cargo/contrib/ 73 | 74 | ## License 75 | 76 | Cargo is primarily distributed under the terms of both the MIT license 77 | and the Apache License (Version 2.0). 78 | 79 | See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT) for details. 80 | 81 | ### Third party software 82 | 83 | This product includes software developed by the OpenSSL Project 84 | for use in the OpenSSL Toolkit (https://www.openssl.org/). 85 | 86 | In binary form, this product includes software that is licensed under the 87 | terms of the GNU General Public License, version 2, with a linking exception, 88 | which can be obtained from the [upstream repository][1]. 89 | 90 | See [LICENSE-THIRD-PARTY](LICENSE-THIRD-PARTY) for details. 91 | 92 | [1]: https://github.com/libgit2/libgit2 93 | 94 | -------------------------------------------------------------------------------- /src/guide/dependencies.md: -------------------------------------------------------------------------------- 1 | ## Dependencies 2 | 3 | [crates.io] is the Rust community's central [*package registry*][def-package-registry] 4 | that serves as a location to discover and download 5 | [packages][def-package]. `cargo` is configured to use it by default to find 6 | requested packages. 7 | 8 | To depend on a library hosted on [crates.io], add it to your `Cargo.toml`. 9 | 10 | [crates.io]: https://crates.io/ 11 | 12 | ### Adding a dependency 13 | 14 | If your `Cargo.toml` doesn't already have a `[dependencies]` section, add 15 | that, then list the [crate][def-crate] name and version that you would like to 16 | use. This example adds a dependency of the `time` crate: 17 | 18 | ```toml 19 | [dependencies] 20 | time = "0.1.12" 21 | ``` 22 | 23 | The version string is a [SemVer] version requirement. The [specifying 24 | dependencies](../reference/specifying-dependencies.md) docs have more information about 25 | the options you have here. 26 | 27 | [SemVer]: https://semver.org 28 | 29 | If we also wanted to add a dependency on the `regex` crate, we would not need 30 | to add `[dependencies]` for each crate listed. Here's what your whole 31 | `Cargo.toml` file would look like with dependencies on the `time` and `regex` 32 | crates: 33 | 34 | ```toml 35 | [package] 36 | name = "hello_world" 37 | version = "0.1.0" 38 | edition = "2021" 39 | 40 | [dependencies] 41 | time = "0.1.12" 42 | regex = "0.1.41" 43 | ``` 44 | 45 | Re-run `cargo build`, and Cargo will fetch the new dependencies and all of 46 | their dependencies, compile them all, and update the `Cargo.lock`: 47 | 48 | ```console 49 | $ cargo build 50 | Updating crates.io index 51 | Downloading memchr v0.1.5 52 | Downloading libc v0.1.10 53 | Downloading regex-syntax v0.2.1 54 | Downloading memchr v0.1.5 55 | Downloading aho-corasick v0.3.0 56 | Downloading regex v0.1.41 57 | Compiling memchr v0.1.5 58 | Compiling libc v0.1.10 59 | Compiling regex-syntax v0.2.1 60 | Compiling memchr v0.1.5 61 | Compiling aho-corasick v0.3.0 62 | Compiling regex v0.1.41 63 | Compiling hello_world v0.1.0 (file:///path/to/package/hello_world) 64 | ``` 65 | 66 | Our `Cargo.lock` contains the exact information about which revision of all of 67 | these dependencies we used. 68 | 69 | Now, if `regex` gets updated, we will still build with the same revision until 70 | we choose to `cargo update`. 71 | 72 | You can now use the `regex` library in `main.rs`. 73 | 74 | ```rust,ignore 75 | use regex::Regex; 76 | 77 | fn main() { 78 | let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap(); 79 | println!("Did our date match? {}", re.is_match("2014-01-01")); 80 | } 81 | ``` 82 | 83 | Running it will show: 84 | 85 | ```console 86 | $ cargo run 87 | Running `target/hello_world` 88 | Did our date match? true 89 | ``` 90 | 91 | [def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' 92 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 93 | [def-package-registry]: ../appendix/glossary.md#package-registry '"package-registry" (glossary entry)' 94 | -------------------------------------------------------------------------------- /src/reference/workspaces.zh.md: -------------------------------------------------------------------------------- 1 | ## Workspaces 2 | 3 | 一个 _工作空间_ 是一个或多个包的集合，这些包共享，公共依赖项解析（具有共享的`Cargo.lock`），输出目录，以及各种设置，如配置文件。属于工作区的包称为*工作区成员*。工作区有两种风格：根包或虚拟清单。 4 | 5 | ### Root package 6 | 7 | 添加[`[workspace]` section](#the-workspace-section)到`Cargo.toml`，创建工作空间。若已经定义了一个`[package]`，在这种情况下，该包是*根包*工作空间的一部分。*工作区根目录*是这个`Cargo.toml`的所在。 8 | 9 | ### Virtual manifest 10 | 11 | 或者，一个`Cargo.toml`可以使用`[workspace]`部分，但没有[`[package]` section][package]。这叫做*虚拟清单*。这在你没有“主”包，或仅希望将所有包分开组织时，使用。 12 | 13 | ### Key features 14 | 15 | 工作区的关键点是： 16 | 17 | - 所有包共享一个公共`Cargo.lock`，位于*工作区根目录*。 18 | - 所有包共享一个公共[输出目录][output directory]，默认为`target`，位在*工作区根目录*。 19 | - 这个[`[patch]`][patch], [`[replace]`][replace]和[`[profile.*]`][profiles]仅在*根* manifest 有效，而对成员的 manifest 忽略。 20 | 21 | ### The `[workspace]` section 22 | 23 | 这个`[workspace]`表格，定义哪些包是工作区的成员： 24 | 25 | ```toml 26 | [workspace] 27 | members = ["member1", "path/to/member2", "crates/*"] 28 | exclude = ["crates/foo", "path/to/other"] 29 | ``` 30 | 31 | 驻留在工作区目录中，全部的[`path`依赖项][`path` dependencies]将自动成为成员。其他成员可以在`members`列出，它应该是一个字符串数组，其字符串为包含`Cargo.toml`文件的目录。 32 | 33 | 这个`members`列表还支持[globs]，去匹配多个路径 —— 典型的文件名 glob 模式，如`*`和`?`。 34 | 35 | 这个`exclude`字段，排除定义的路径，让它们不能加入或移出工作区（可用 glob 模式）。 36 | 37 | 例如：给个空`[workspace]`表，配合上`[package]`，就能以 package 与它的所有 path 依赖项，方便地创建一个工作区。 38 | 39 | ### Workspace selection 40 | 41 | 在工作区的子目录中时，Cargo 会在父目录，自动搜索`Cargo.toml`的`[workspace]`定义，以确定要使用的工作空间。[`package.workspace`]可用在成员箱子中，指向工作区的根，以覆盖此自动搜索。如果成员不在工作区根目录的子目录中，是要手动设置的。 42 | 43 | ### Package selection 44 | 45 | 在工作区中，与包相关的 Cargo 命令，比如[`cargo build`]，它可以使用`-p` / `--package`或`--workspace`命令行标志，确定要对哪些包进行操作。如果未指定这两个标志，Cargo 将使用当前工作目录中的包。如果当前目录是虚拟工作区，它将应用于所有成员（就像`--workspace`已在命令行上指定）。 46 | 47 | 可选的`default-members`，设置在工作区根目录中，要操作的成员（命令行不指定的情况下）： 48 | 49 | ```toml 50 | [workspace] 51 | members = ["path/to/member1", "path/to/member2", "path/to/member3/*"] 52 | default-members = ["path/to/member2", "path/to/member3/foo"] 53 | ``` 54 | 55 | 如有规定，`default-members`必须扩展到`members`. 56 | 57 | ### The `workspace.metadata` table 58 | 59 | 这个`workspace.metadata`表被 Cargo 忽略，不会被警告。`Cargo.toml`中这个表格，是给那些要存储工作区配置的工具所使用的。例如： 60 | 61 | ```toml 62 | [workspace] 63 | members = ["member1", "member2"] 64 | 65 | [workspace.metadata.webcontents] 66 | root = "path/to/webproject" 67 | tool = ["npm", "run", "build"] 68 | # ... 69 | ``` 70 | 71 | 在包级别，有一组类似的表[`package.metadata`][package-metadata]。虽然 cargo 没有为这两个表格的内容指定格式，但，建议外部工具可能希望以一致的方式使用它们，例子：如果`package.metadata`数据丢失，就可以参考`workspace.metadata`表中的数据，对工具可能用得上。 72 | 73 | [package]: manifest.zh.md#the-package-section 74 | [package-metadata]: manifest.zh.md#the-metadata-table 75 | [output directory]: ../guide/build-cache.zh.md 76 | [patch]: overriding-dependencies.zh.md#the-patch-section 77 | [replace]: overriding-dependencies.zh.md#the-replace-section 78 | [profiles]: profiles.zh.md 79 | [`path` dependencies]: specifying-dependencies.zh.md#specifying-path-dependencies 80 | [`package.workspace`]: manifest.zh.md#the-workspace-field 81 | [globs]: https://docs.rs/glob/0.3.0/glob/struct.Pattern.html 82 | [`cargo build`]: ../commands/cargo-build.zh.md 83 | -------------------------------------------------------------------------------- /src/guide/continuous-integration.zh.md: -------------------------------------------------------------------------------- 1 | ## 持续集成 2 | 3 | ### Travis CI 4 | 5 | 要在 Travis CI 上测试您的项目，这里有一个`.travis.yml`文件示例: 6 | 7 | ```yaml 8 | language: rust 9 | rust: 10 | - stable 11 | - beta 12 | - nightly 13 | matrix: 14 | allow_failures: 15 | - rust: nightly 16 | ``` 17 | 18 | 这将在所有三个 rust 版本下，进行测试，但 nightly 的任何破坏，都不会使整体构建失败。请看看[Travis CI Rust 文档](https://docs.travis-ci.com/user/languages/rust/)了解更多信息. 19 | 20 | ### GitHub Actions 21 | 22 | GitHub Actions 中，测试项目, 这里有个简单的 `.github/workflows/ci.yml` 文件: 23 | 24 | ```yaml 25 | name: Cargo Build & Test 26 | 27 | on: 28 | push: 29 | pull_request: 30 | 31 | env: 32 | CARGO_TERM_COLOR: always 33 | 34 | jobs: 35 | build_and_test: 36 | name: Rust project - latest 37 | runs-on: ubuntu-latest 38 | strategy: 39 | matrix: 40 | toolchain: 41 | - stable 42 | - beta 43 | - nightly 44 | steps: 45 | - uses: actions/checkout@v2 46 | - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }} 47 | - run: cargo build --verbose 48 | - run: cargo test --verbose 49 | ``` 50 | 51 | 这会测试三个 release channels (注意：一个错，整个测试流程就会是错误的)。 你还可以在 Github 上面， `"Actions" > "new workflow"` ，并选择 Rust ，将 [default configuration](https://github.com/actions/starter-workflows/blob/main/ci/rust.yml) 添加到你的库。 [GitHub Actions 文档](https://docs.github.com/en/actions)有更多信息。 52 | 53 | ### GitLab CI 54 | 55 | 要在 GitLab CI 上测试您的包，这里有一个`.gitlab-ci.yml`文件示例: 56 | 57 | ```yaml 58 | stages: 59 | - build 60 | 61 | rust-latest: 62 | stage: build 63 | image: rust:latest 64 | script: 65 | - cargo build --verbose 66 | - cargo test --verbose 67 | 68 | rust-nightly: 69 | stage: build 70 | image: rustlang/rust:nightly 71 | script: 72 | - cargo build --verbose 73 | - cargo test --verbose 74 | allow_failure: true 75 | ``` 76 | 77 | 这将测试 stable 版本和 nightly 版本，但 nightly 的任何破损，都不会使整体构建失败。欲获得更多信息，请看[GitLab CI](https://docs.gitlab.com/ce/ci/yaml/README.md). 78 | 79 | ### builds.sr.ht 80 | 81 | 在 sr.ht 测试你的项目, 在这里有个简单 `.build.yml` 文件。 82 | 要记得，更改你 `` 和 ``。 83 | 84 | ```yaml 85 | image: archlinux 86 | packages: 87 | - rustup 88 | sources: 89 | - 90 | tasks: 91 | - setup: | 92 | rustup toolchain install nightly stable 93 | cd / 94 | rustup run stable cargo fetch 95 | - stable: | 96 | rustup default stable 97 | cd / 98 | cargo build --verbose 99 | cargo test --verbose 100 | - nightly: | 101 | rustup default nightly 102 | cd / 103 | cargo build --verbose ||: 104 | cargo test --verbose ||: 105 | - docs: | 106 | cd / 107 | rustup run stable cargo doc --no-deps 108 | rustup run nightly cargo doc --no-deps ||: 109 | ``` 110 | 111 | 这会在 stable channel 和 nightly 112 | channel 上构建文档和测试, 但 nightly 版本的一个崩溃，不会对整个构建产生影响。 [builds.sr.ht 文档](https://man.sr.ht/builds.sr.ht/) 有更多的信息。 113 | 114 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 115 | -------------------------------------------------------------------------------- /src/appendix/git-authentication.md: -------------------------------------------------------------------------------- 1 | # Git Authentication 2 | 3 | Cargo supports some forms of authentication when using git dependencies and 4 | registries. This appendix contains some information for setting up git 5 | authentication in a way that works with Cargo. 6 | 7 | If you need other authentication methods, the [`net.git-fetch-with-cli`] 8 | config value can be set to cause Cargo to execute the `git` executable to 9 | handle fetching remote repositories instead of using the built-in support. 10 | This can be enabled with the `CARGO_NET_GIT_FETCH_WITH_CLI=true` environment 11 | variable. 12 | 13 | ## HTTPS authentication 14 | 15 | HTTPS authentication requires the [`credential.helper`] mechanism. There are 16 | multiple credential helpers, and you specify the one you want to use in your 17 | global git configuration file. 18 | 19 | ```ini 20 | # ~/.gitconfig 21 | 22 | [credential] 23 | helper = store 24 | ``` 25 | 26 | Cargo does not ask for passwords, so for most helpers you will need to give 27 | the helper the initial username/password before running Cargo. One way to do 28 | this is to run `git clone` of the private git repo and enter the 29 | username/password. 30 | 31 | > **Tip:**
32 | > macOS users may want to consider using the osxkeychain helper.
33 | > Windows users may want to consider using the [GCM] helper. 34 | 35 | > **Note:** Windows users will need to make sure that the `sh` shell is 36 | > available in your `PATH`. This typically is available with the Git for 37 | > Windows installation. 38 | 39 | ## SSH authentication 40 | 41 | SSH authentication requires `ssh-agent` to be running to acquire the SSH key. 42 | Make sure the appropriate environment variables are set up (`SSH_AUTH_SOCK` on 43 | most Unix-like systems), and that the correct keys are added (with `ssh-add`). 44 | 45 | Windows can use Pageant (part of [PuTTY]) or `ssh-agent`. 46 | To use `ssh-agent`, Cargo needs to use the OpenSSH that is distributed as part 47 | of Windows, as Cargo does not support the simulated Unix-domain sockets used 48 | by MinGW or Cygwin. 49 | More information about installing with Windows can be found at the [Microsoft 50 | installation documentation] and the page on [key management] has instructions 51 | on how to start `ssh-agent` and to add keys. 52 | 53 | > **Note:** Cargo does not support git's shorthand SSH URLs like 54 | > `git@example.com:user/repo.git`. Use a full SSH URL like 55 | > `ssh://git@example.com/user/repo.git`. 56 | 57 | > **Note:** SSH configuration files (like OpenSSH's `~/.ssh/config`) are not 58 | > used by Cargo's built-in SSH library. More advanced requirements should use 59 | > [`net.git-fetch-with-cli`]. 60 | 61 | [`credential.helper`]: https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage 62 | [`net.git-fetch-with-cli`]: ../reference/config.md#netgit-fetch-with-cli 63 | [GCM]: https://github.com/microsoft/Git-Credential-Manager-Core/ 64 | [PuTTY]: https://www.chiark.greenend.org.uk/~sgtatham/putty/ 65 | [Microsoft installation documentation]: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse 66 | [key management]: https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_keymanagement 67 | -------------------------------------------------------------------------------- /src/reference/source-replacement.zh.md: -------------------------------------------------------------------------------- 1 | ## 来源 更换 2 | 3 | 本文档是关于更换 crate 索引(注册表)。您可以阅读有关重写依赖项的信息，它在本文档的[重写依赖关系][overriding]部分。 4 | 5 | Cargo 支持**用另一个来源更换一个来源**的能力，可根据镜像或 vendoring 依赖关系来表达倾向。要配置这些，目前通过[`.cargo/config`配置][config]机制完成，像这样: 6 | 7 | [config]: reference/config.md 8 | 9 | ```toml 10 | # `source` 表下，就是存储有关要更换的来源名称 11 | [source] 12 | 13 | # 在`source` 表格之下的，可为一定数量的有关来源名称. 示例下面就# 定义了一个新源， 叫 `my-awesome-source`， 其内容来自本地 # `vendor`目录 ，其相对于包含`.cargo/config`文件的目录 14 | [source.my-awesome-source] 15 | directory = "vendor" 16 | 17 | # Git sources 也指定一个 branch/tag/rev 18 | git = "https://example.com/path/to/repo" 19 | # branch = "master" 20 | # tag = "v1.0.1" 21 | # rev = "313f44e8" 22 | 23 | # The crates.io 默认源 在"crates-io"名称下， 且在这里我们使用 `replace-with` 字段指明 默认源更换成"my-awesome-source"源 24 | [source.crates-io] 25 | replace-with = "my-awesome-source" 26 | ``` 27 | 28 | 使用此配置，Cargo 会尝试在"vendor"目录中，查找所有包，而不是 查询在线注册表 crates.io 。Cargo 有两种来源更换的表达 : 29 | 30 | - 供应(Vendoring) - 可以定义自定义源，它们表示本地文件系统上的包。这些源是它们正在更换的源的子集，并在需要时可以检入包中。 31 | 32 | - 镜像(Mirroring) - 可以更换为等效版本的源，行为表现为 crates.io 本身的缓存。 33 | 34 | Cargo 有一个关于来源更换的核心假设，源代码从两个完全相同的源而来。在上面的例子中，Cargo 假设所有的箱子都来自`my-awesome-source`，与`crates-io`副本完全相同。请注意，这也意味着`my-awesome-source`，不允许有`crates-io`源不存在的箱。 35 | 36 | 因此，来源更换不适用于依赖项补丁(fix bug)，或私有注册表等情况。Cargo 是通过使用[`[replace]`字段][replace-section]支持依赖项补丁，计划为未来版本的 Cargo 提供私人注册表的支持。 37 | 38 | [replace-section]: reference/manifest.md#the-replace-section 39 | [overriding]: reference/specifying-dependencies.md#overriding-dependencies 40 | 41 | ### 配置 42 | 43 | 更换源的配置通过完成[`.cargo/config`][config]，下面为全套可用字段是: 44 | 45 | ```toml 46 | # 每个源都有自己的表格，名称即是表名 47 | [source.the-source-name] 48 | 49 | # 命令 ，`the-source-name` 会被`another-source`取代 50 | replace-with = "another-source" 51 | 52 | # 有几种可用的源定义(接下来有所描述) 53 | registry = "https://example.com/path/to/index" 54 | local-registry = "path/to/registry" 55 | directory = "path/to/vendor" 56 | ``` 57 | 58 | `crates-io`代表 crates.io 在线注册表(箱的默认来源)，可以更换为: 59 | 60 | ```toml 61 | [source.crates-io] 62 | replace-with = 'another-source' 63 | ``` 64 | 65 | ### 注册表源 66 | 67 | "注册表源"与 crates.io 本身相同。也就是说，它也有一个在 git 存储库中提供的索引，该存储库匹配[crates.io index](https://github.com/rust-lang/crates.io-index)的格式。然后该存储库具有指示从哪里下载包的配置。 68 | 69 | 目前还没有一个已经设置 crates.io 的镜像的可用项目。请继续关注! 70 | 71 | > 中国用户，可搜索 'rust 换 中科大 源' 72 | 73 | ### 本地 注册表源 74 | 75 | "本地注册表源"旨在成为另一个注册表源的子集，但可在本地文件系统(也称为 vendoring)上使用。本地注册表是提前下载，通常与一个 `Cargo.lock`同步，并由一组`*.crate`文件和像普通注册表一样的索引组成。 76 | 77 | 管理和创建本地注册表源的主要方法是通过[`cargo-local-registry`][cargo-local-registry]子命令，可在 crates.io 上找到，并用`cargo install cargo-local-registry`安装。 78 | 79 | [cargo-local-registry]: https://crates.io/crates/cargo-local-registry 80 | 81 | 本地注册表包含在一个目录，其中包含许多从 crates.io 下载的`*.crate`文件，以及`index`目录，它与 crates.io-index 项目目录具有相同格式(仅填充有存在的 crates). 82 | 83 | ### 目录 源 84 | 85 | "目录源"类似于本地注册表源，其中包含本地文件系统上许多的可用包，适用于 vendoring 依赖项。与本地注册表一样，目录源主要由外部子命令管理[`cargo-vendor`][cargo-vendor]，可用`cargo install cargo-vendor`安装。 86 | 87 | [cargo-vendor]: https://crates.io/crates/cargo-vendor 88 | 89 | 目录源与本地注册表不同，但它们包含`*.crate`文件的解压缩版本，使其在某些情况下，更适合检查所有内容到源代码控制工具。目录源只是一个包含许多其他目录的目录，其中包含 crates 的源代码(解压缩版本的`*.crate`文件)。目前，对每个目录的名称没有限制。 90 | 91 | 目录源中的每个包也有一个关联的元数据文件，指示包中每个文件的校验和，以防止意外修改。 92 | -------------------------------------------------------------------------------- /src/guide/why-cargo-exists.md: -------------------------------------------------------------------------------- 1 | ## Why Cargo Exists 2 | 3 | ### Preliminaries 4 | 5 | In Rust, as you may know, a library or executable program is called a 6 | [*crate*][def-crate]. Crates are compiled using the Rust compiler, 7 | `rustc`. When starting with Rust, the first source code most people encounter 8 | is that of the venerable “hello world” program, which they compile by invoking 9 | `rustc` directly: 10 | 11 | ```console 12 | $ rustc hello.rs 13 | $ ./hello 14 | Hello, world! 15 | ``` 16 | 17 | Note that the above command required that we specify the file name 18 | explicitly. If we were to directly use `rustc` to compile a different program, 19 | a different command line invocation would be required. If we needed to specify 20 | any specific compiler flags or include external dependencies, then the 21 | needed command would be even more specific (and elaborate). 22 | 23 | Furthermore, most non-trivial programs will likely have dependencies on 24 | external libraries, and will therefore also depend transitively on *their* 25 | dependencies. Obtaining the correct versions of all the necessary dependencies 26 | and keeping them up to date would be laborious and error-prone if done by 27 | hand. 28 | 29 | Rather than work only with crates and `rustc`, we can avoid the manual tedium 30 | involved with performing the above tasks by introducing a higher-level 31 | ["*package*"][def-package] abstraction and by using a 32 | [*package manager*][def-package-manager]. 33 | 34 | ### Enter: Cargo 35 | 36 | *Cargo* is the Rust package manager. It is a tool that allows Rust 37 | [*packages*][def-package] to declare their various dependencies and ensure 38 | that you’ll always get a repeatable build. 39 | 40 | To accomplish this goal, Cargo does four things: 41 | 42 | * Introduces two metadata files with various bits of package information. 43 | * Fetches and builds your package’s dependencies. 44 | * Invokes `rustc` or another build tool with the correct parameters to build 45 | your package. 46 | * Introduces conventions to make working with Rust packages easier. 47 | 48 | To a large extent, Cargo normalizes the commands needed to build a given 49 | program or library; this is one aspect to the above mentioned conventions. As 50 | we show later, the same command can be used to build different 51 | [*artifacts*][def-artifact], regardless of their names. Rather than invoke 52 | `rustc` directly, we can instead invoke something generic such as `cargo 53 | build` and let cargo worry about constructing the correct `rustc` 54 | invocation. Furthermore, Cargo will automatically fetch from a 55 | [*registry*][def-registry] any dependencies we have defined for our artifact, 56 | and arrange for them to be incorporated into our build as needed. 57 | 58 | It is only a slight exaggeration to say that once you know how to build one 59 | Cargo-based project, you know how to build *all* of them. 60 | 61 | [def-artifact]: ../appendix/glossary.md#artifact '"artifact" (glossary entry)' 62 | [def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' 63 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 64 | [def-package-manager]: ../appendix/glossary.md#package-manager '"package manager" (glossary entry)' 65 | [def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)' 66 | -------------------------------------------------------------------------------- /src/reference/pkgid-spec.md: -------------------------------------------------------------------------------- 1 | ## Package ID Specifications 2 | 3 | ### Package ID specifications 4 | 5 | Subcommands of Cargo frequently need to refer to a particular package within a 6 | dependency graph for various operations like updating, cleaning, building, etc. 7 | To solve this problem, Cargo supports *Package ID Specifications*. A specification 8 | is a string which is used to uniquely refer to one package within a graph of 9 | packages. 10 | 11 | The specification may be fully qualified, such as 12 | `https://github.com/rust-lang/crates.io-index#regex:1.4.3` or it may be 13 | abbreviated, such as `regex`. The abbreviated form may be used as long as it 14 | uniquely identifies a single package in the dependency graph. If there is 15 | ambiguity, additional qualifiers can be added to make it unique. For example, 16 | if there are two versions of the `regex` package in the graph, then it can be 17 | qualified with a version to make it unique, such as `regex:1.4.3`. 18 | 19 | #### Specification grammar 20 | 21 | The formal grammar for a Package Id Specification is: 22 | 23 | ```notrust 24 | spec := pkgname 25 | | proto "://" hostname-and-path [ "#" ( pkgname | semver ) ] 26 | pkgname := name [ ":" semver ] 27 | 28 | proto := "http" | "git" | ... 29 | ``` 30 | 31 | Here, brackets indicate that the contents are optional. 32 | 33 | The URL form can be used for git dependencies, or to differentiate packages 34 | that come from different sources such as different registries. 35 | 36 | #### Example specifications 37 | 38 | The following are references to the `regex` package on `crates.io`: 39 | 40 | | Spec | Name | Version | 41 | |:------------------------------------------------------------|:-------:|:-------:| 42 | | `regex` | `regex` | `*` | 43 | | `regex:1.4.3` | `regex` | `1.4.3` | 44 | | `https://github.com/rust-lang/crates.io-index#regex` | `regex` | `*` | 45 | | `https://github.com/rust-lang/crates.io-index#regex:1.4.3` | `regex` | `1.4.3` | 46 | 47 | The following are some examples of specs for several different git dependencies: 48 | 49 | | Spec | Name | Version | 50 | |:----------------------------------------------------------|:----------------:|:--------:| 51 | | `https://github.com/rust-lang/cargo#0.52.0` | `cargo` | `0.52.0` | 52 | | `https://github.com/rust-lang/cargo#cargo-platform:0.1.2` | `cargo-platform` | `0.1.2` | 53 | | `ssh://git@github.com/rust-lang/regex.git#regex:1.4.3` | `regex` | `1.4.3` | 54 | 55 | Local packages on the filesystem can use `file://` URLs to reference them: 56 | 57 | | Spec | Name | Version | 58 | |:---------------------------------------|:-----:|:-------:| 59 | | `file:///path/to/my/project/foo` | `foo` | `*` | 60 | | `file:///path/to/my/project/foo#1.1.8` | `foo` | `1.1.8` | 61 | 62 | #### Brevity of specifications 63 | 64 | The goal of this is to enable both succinct and exhaustive syntaxes for 65 | referring to packages in a dependency graph. Ambiguous references may refer to 66 | one or more packages. Most commands generate an error if more than one package 67 | could be referred to with the same specification. 68 | -------------------------------------------------------------------------------- /src/guide/continuous-integration.md: -------------------------------------------------------------------------------- 1 | ## Continuous Integration 2 | 3 | ### Travis CI 4 | 5 | To test your [package][def-package] on Travis CI, here is a sample 6 | `.travis.yml` file: 7 | 8 | ```yaml 9 | language: rust 10 | rust: 11 | - stable 12 | - beta 13 | - nightly 14 | matrix: 15 | allow_failures: 16 | - rust: nightly 17 | ``` 18 | 19 | This will test all three release channels, but any breakage in nightly 20 | will not fail your overall build. Please see the [Travis CI Rust 21 | documentation](https://docs.travis-ci.com/user/languages/rust/) for more 22 | information. 23 | 24 | ### GitHub Actions 25 | 26 | To test your package on GitHub Actions, here is a sample `.github/workflows/ci.yml` file: 27 | 28 | ```yaml 29 | name: Cargo Build & Test 30 | 31 | on: 32 | push: 33 | pull_request: 34 | 35 | env: 36 | CARGO_TERM_COLOR: always 37 | 38 | jobs: 39 | build_and_test: 40 | name: Rust project - latest 41 | runs-on: ubuntu-latest 42 | strategy: 43 | matrix: 44 | toolchain: 45 | - stable 46 | - beta 47 | - nightly 48 | steps: 49 | - uses: actions/checkout@v2 50 | - run: rustup update ${{ matrix.toolchain }} && rustup default ${{ matrix.toolchain }} 51 | - run: cargo build --verbose 52 | - run: cargo test --verbose 53 | 54 | ``` 55 | 56 | This will test all three release channels (note a failure in any toolchain version will fail the entire job). You can also click `"Actions" > "new workflow"` in the GitHub UI and select Rust to add the [default configuration](https://github.com/actions/starter-workflows/blob/main/ci/rust.yml) to your repo. See [GitHub Actions documentation](https://docs.github.com/en/actions) for more information. 57 | 58 | ### GitLab CI 59 | 60 | To test your package on GitLab CI, here is a sample `.gitlab-ci.yml` file: 61 | 62 | ```yaml 63 | stages: 64 | - build 65 | 66 | rust-latest: 67 | stage: build 68 | image: rust:latest 69 | script: 70 | - cargo build --verbose 71 | - cargo test --verbose 72 | 73 | rust-nightly: 74 | stage: build 75 | image: rustlang/rust:nightly 76 | script: 77 | - cargo build --verbose 78 | - cargo test --verbose 79 | allow_failure: true 80 | ``` 81 | 82 | This will test on the stable channel and nightly channel, but any 83 | breakage in nightly will not fail your overall build. Please see the 84 | [GitLab CI documentation](https://docs.gitlab.com/ce/ci/yaml/index.html) for more 85 | information. 86 | 87 | ### builds.sr.ht 88 | 89 | To test your package on sr.ht, here is a sample `.build.yml` file. 90 | Be sure to change `` and `` to the repo to clone and 91 | the directory where it was cloned. 92 | 93 | ```yaml 94 | image: archlinux 95 | packages: 96 | - rustup 97 | sources: 98 | - 99 | tasks: 100 | - setup: | 101 | rustup toolchain install nightly stable 102 | cd / 103 | rustup run stable cargo fetch 104 | - stable: | 105 | rustup default stable 106 | cd / 107 | cargo build --verbose 108 | cargo test --verbose 109 | - nightly: | 110 | rustup default nightly 111 | cd / 112 | cargo build --verbose ||: 113 | cargo test --verbose ||: 114 | - docs: | 115 | cd / 116 | rustup run stable cargo doc --no-deps 117 | rustup run nightly cargo doc --no-deps ||: 118 | ``` 119 | 120 | This will test and build documentation on the stable channel and nightly 121 | channel, but any breakage in nightly will not fail your overall build. Please 122 | see the [builds.sr.ht documentation](https://man.sr.ht/builds.sr.ht/) for more 123 | information. 124 | 125 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 126 | -------------------------------------------------------------------------------- /contrib/src/architecture/console.md: -------------------------------------------------------------------------------- 1 | # Console Output 2 | 3 | All of Cargo's output should go through the [`Shell`] struct. You can normally 4 | obtain the `Shell` instance from the [`Config`] struct. Do **not** use the std 5 | `println!` macros. 6 | 7 | Most of Cargo's output goes to stderr. When running in JSON mode, the output 8 | goes to stdout. 9 | 10 | It is important to properly handle errors when writing to the console. 11 | Informational commands, like `cargo list`, should ignore any errors writing 12 | the output. There are some [`drop_print`] macros that are intended to make 13 | this easier. 14 | 15 | Messages written during compilation should handle errors, and abort the build 16 | if they are unable to be displayed. This is generally automatically handled in 17 | the [`JobQueue`] as it processes each message. 18 | 19 | [`Shell`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/shell.rs 20 | [`Config`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/config/mod.rs 21 | [`drop_print`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1820-L1848 22 | [`JobQueue`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/job_queue.rs 23 | 24 | ## Errors 25 | 26 | Cargo uses [`anyhow`] for managing errors. This makes it convenient to "chain" 27 | errors together, so that Cargo can report how an error originated, and what it 28 | was trying to do at the time. 29 | 30 | Error helpers are implemented in the [`errors`] module. Use the 31 | `InternalError` error type for errors that are not expected to happen. This 32 | will print a message to the user to file a bug report. 33 | 34 | The binary side of Cargo uses the `CliError` struct to wrap the process exit 35 | code. Usually Cargo exits with 101 for an error, but some commands like `cargo 36 | test` will exit with different codes. 37 | 38 | [`errors`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/errors.rs 39 | 40 | ## Style 41 | 42 | Some guidelines for Cargo's output: 43 | 44 | * Keep the normal output brief. Cargo is already fairly noisy, so try to keep 45 | the output as brief and clean as possible. 46 | * Good error messages are very important! Try to keep them brief and to the 47 | point, but good enough that a beginner can understand what is wrong and can 48 | figure out how to fix. It is a difficult balance to hit! Err on the side of 49 | providing extra information. 50 | * When using any low-level routines, such as `std::fs`, *always* add error 51 | context about what it is doing. For example, reading from a file should 52 | include context about which file is being read if there is an error. 53 | * Cargo's error style is usually a phrase, starting with a lowercase letter. 54 | If there is a longer error message that needs multiple sentences, go ahead 55 | and use multiple sentences. This should probably be improved sometime in the 56 | future to be more structured. 57 | 58 | ## Debug logging 59 | 60 | Cargo uses the [`env_logger`] crate to display debug log messages. The 61 | `CARGO_LOG` environment variable can be set to enable debug logging, with a 62 | value such as `trace`, `debug`, or `warn`. It also supports filtering for 63 | specific modules. Feel free to use the standard [`log`] macros to help with 64 | diagnosing problems. 65 | 66 | ```sh 67 | # Outputs all logs with levels debug and higher 68 | CARGO_LOG=debug cargo generate-lockfile 69 | 70 | # Don't forget that you can filter by module as well 71 | CARGO_LOG=cargo::core::resolver=trace cargo generate-lockfile 72 | 73 | # This will print lots of info about the download process. `trace` prints even more. 74 | CARGO_HTTP_DEBUG=true CARGO_LOG=cargo::ops::registry=debug cargo fetch 75 | 76 | # This is an important command for diagnosing fingerprint issues. 77 | CARGO_LOG=cargo::core::compiler::fingerprint=trace cargo build 78 | ``` 79 | 80 | [`env_logger`]: https://docs.rs/env_logger 81 | [`log`]: https://docs.rs/log 82 | [`anyhow`]: https://docs.rs/anyhow 83 | -------------------------------------------------------------------------------- /docs/fonts/fonts.css: -------------------------------------------------------------------------------- 1 | /* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */ 2 | /* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */ 3 | 4 | /* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 5 | @font-face { 6 | font-family: 'Open Sans'; 7 | font-style: normal; 8 | font-weight: 300; 9 | src: local('Open Sans Light'), local('OpenSans-Light'), 10 | url('open-sans-v17-all-charsets-300.woff2') format('woff2'); 11 | } 12 | 13 | /* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 14 | @font-face { 15 | font-family: 'Open Sans'; 16 | font-style: italic; 17 | font-weight: 300; 18 | src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'), 19 | url('open-sans-v17-all-charsets-300italic.woff2') format('woff2'); 20 | } 21 | 22 | /* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 23 | @font-face { 24 | font-family: 'Open Sans'; 25 | font-style: normal; 26 | font-weight: 400; 27 | src: local('Open Sans Regular'), local('OpenSans-Regular'), 28 | url('open-sans-v17-all-charsets-regular.woff2') format('woff2'); 29 | } 30 | 31 | /* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 32 | @font-face { 33 | font-family: 'Open Sans'; 34 | font-style: italic; 35 | font-weight: 400; 36 | src: local('Open Sans Italic'), local('OpenSans-Italic'), 37 | url('open-sans-v17-all-charsets-italic.woff2') format('woff2'); 38 | } 39 | 40 | /* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 41 | @font-face { 42 | font-family: 'Open Sans'; 43 | font-style: normal; 44 | font-weight: 600; 45 | src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'), 46 | url('open-sans-v17-all-charsets-600.woff2') format('woff2'); 47 | } 48 | 49 | /* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 50 | @font-face { 51 | font-family: 'Open Sans'; 52 | font-style: italic; 53 | font-weight: 600; 54 | src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'), 55 | url('open-sans-v17-all-charsets-600italic.woff2') format('woff2'); 56 | } 57 | 58 | /* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 59 | @font-face { 60 | font-family: 'Open Sans'; 61 | font-style: normal; 62 | font-weight: 700; 63 | src: local('Open Sans Bold'), local('OpenSans-Bold'), 64 | url('open-sans-v17-all-charsets-700.woff2') format('woff2'); 65 | } 66 | 67 | /* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 68 | @font-face { 69 | font-family: 'Open Sans'; 70 | font-style: italic; 71 | font-weight: 700; 72 | src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'), 73 | url('open-sans-v17-all-charsets-700italic.woff2') format('woff2'); 74 | } 75 | 76 | /* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 77 | @font-face { 78 | font-family: 'Open Sans'; 79 | font-style: normal; 80 | font-weight: 800; 81 | src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'), 82 | url('open-sans-v17-all-charsets-800.woff2') format('woff2'); 83 | } 84 | 85 | /* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */ 86 | @font-face { 87 | font-family: 'Open Sans'; 88 | font-style: italic; 89 | font-weight: 800; 90 | src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'), 91 | url('open-sans-v17-all-charsets-800italic.woff2') format('woff2'); 92 | } 93 | 94 | /* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */ 95 | @font-face { 96 | font-family: 'Source Code Pro'; 97 | font-style: normal; 98 | font-weight: 500; 99 | src: url('source-code-pro-v11-all-charsets-500.woff2') format('woff2'); 100 | } 101 | -------------------------------------------------------------------------------- /.mds-list: -------------------------------------------------------------------------------- 1 | source/src/guide/dependencies.md 2 | source/src/guide/build-cache.md 3 | source/src/guide/project-layout.md 4 | source/src/guide/creating-a-new-project.md 5 | source/src/guide/continuous-integration.md 6 | source/src/guide/working-on-an-existing-project.md 7 | source/src/guide/index.md 8 | source/src/guide/cargo-home.md 9 | source/src/guide/cargo-toml-vs-cargo-lock.md 10 | source/src/guide/why-cargo-exists.md 11 | source/src/guide/tests.md 12 | source/src/getting-started/installation.md 13 | source/src/getting-started/index.md 14 | source/src/getting-started/first-steps.md 15 | source/src/reference/external-tools.md 16 | source/src/reference/future-incompat-report.md 17 | source/src/reference/pkgid-spec.md 18 | source/src/reference/config.md 19 | source/src/reference/overriding-dependencies.md 20 | source/src/reference/features.md 21 | source/src/reference/semver.md 22 | source/src/reference/manifest.md 23 | source/src/reference/profiles.md 24 | source/src/reference/build-scripts.md 25 | source/src/reference/source-replacement.md 26 | source/src/reference/build-script-examples.md 27 | source/src/reference/specifying-dependencies.md 28 | source/src/reference/environment-variables.md 29 | source/src/reference/publishing.md 30 | source/src/reference/unstable.md 31 | source/src/reference/registries.md 32 | source/src/reference/index.md 33 | source/src/reference/features-examples.md 34 | source/src/reference/cargo-targets.md 35 | source/src/reference/workspaces.md 36 | source/src/reference/resolver.md 37 | source/src/faq.md 38 | source/src/appendix/glossary.md 39 | source/src/appendix/git-authentication.md 40 | source/src/index.md 41 | source/src/commands/cargo-run.md 42 | source/src/commands/cargo-clean.md 43 | source/src/commands/cargo-new.md 44 | source/src/commands/cargo-install.md 45 | source/src/commands/cargo-locate-project.md 46 | source/src/commands/cargo-build.md 47 | source/src/commands/manifest-commands.md 48 | source/src/commands/general-commands.md 49 | source/src/commands/cargo-tree.md 50 | source/src/commands/cargo-vendor.md 51 | source/src/commands/build-commands.md 52 | source/src/commands/cargo.md 53 | source/src/commands/cargo-test.md 54 | source/src/commands/cargo-update.md 55 | source/src/commands/cargo-owner.md 56 | source/src/commands/cargo-bench.md 57 | source/src/commands/cargo-metadata.md 58 | source/src/commands/package-commands.md 59 | source/src/commands/publishing-commands.md 60 | source/src/commands/cargo-publish.md 61 | source/src/commands/cargo-help.md 62 | source/src/commands/cargo-fetch.md 63 | source/src/commands/cargo-yank.md 64 | source/src/commands/cargo-rustdoc.md 65 | source/src/commands/cargo-rustc.md 66 | source/src/commands/cargo-uninstall.md 67 | source/src/commands/cargo-generate-lockfile.md 68 | source/src/commands/cargo-pkgid.md 69 | source/src/commands/cargo-report.md 70 | source/src/commands/cargo-fix.md 71 | source/src/commands/cargo-init.md 72 | source/src/commands/index.md 73 | source/src/commands/cargo-check.md 74 | source/src/commands/cargo-search.md 75 | source/src/commands/cargo-verify-project.md 76 | source/src/commands/cargo-doc.md 77 | source/src/commands/cargo-version.md 78 | source/src/commands/cargo-package.md 79 | source/src/commands/cargo-login.md 80 | source/src/SUMMARY.md 81 | source/contrib/src/tests/running.md 82 | source/contrib/src/tests/profiling.md 83 | source/contrib/src/tests/index.md 84 | source/contrib/src/tests/writing.md 85 | source/contrib/src/design.md 86 | source/contrib/src/architecture/console.md 87 | source/contrib/src/architecture/files.md 88 | source/contrib/src/architecture/codebase.md 89 | source/contrib/src/architecture/subcommands.md 90 | source/contrib/src/architecture/compilation.md 91 | source/contrib/src/architecture/packages.md 92 | source/contrib/src/architecture/index.md 93 | source/contrib/src/issues.md 94 | source/contrib/src/process/working-on-cargo.md 95 | source/contrib/src/process/release.md 96 | source/contrib/src/process/unstable.md 97 | source/contrib/src/process/index.md 98 | source/contrib/src/index.md 99 | source/contrib/src/SUMMARY.md 100 | source/contrib/README.md 101 | source/README.md 102 | -------------------------------------------------------------------------------- /contrib/src/process/unstable.md: -------------------------------------------------------------------------------- 1 | # Unstable features 2 | 3 | Most new features should go through the unstable process. This means that the 4 | feature will only be usable on the nightly channel, and requires a specific 5 | opt-in by the user. Small changes can skip this process, but please consult 6 | with the Cargo team first. 7 | 8 | ## Unstable feature opt-in 9 | 10 | For features that require behavior changes or new syntax in `Cargo.toml`, then 11 | it will need a `cargo-features` value placed at the top of `Cargo.toml` to 12 | enable it. The process for doing adding a new feature is described in the 13 | [`features` module]. Code that implements the feature will need to manually 14 | check that the feature is enabled for the current manifest. 15 | 16 | For features that add new command-line flags, config options, or environment 17 | variables, then the `-Z` flags will be needed to enable them. The [`features` 18 | module] also describes how to add these. New flags should use the 19 | `fail_if_stable_opt` method to check if the `-Z unstable-options` flag has 20 | been passed. 21 | 22 | ## Unstable documentation 23 | 24 | Every unstable feature should have a section added to the [unstable chapter] 25 | describing how to use the feature. 26 | 27 | `-Z` CLI flags should be documented in the built-in help in the [`cli` 28 | module]. 29 | 30 | [unstable chapter]: https://github.com/rust-lang/cargo/blob/master/src/doc/src/reference/unstable.md 31 | [`cli` module]: https://github.com/rust-lang/cargo/blob/master/src/bin/cargo/cli.rs 32 | 33 | ## Tracking issues 34 | 35 | Each unstable feature should get a [tracking issue]. These issues are 36 | typically created when a PR is close to being merged, or soon after it is 37 | merged. Use the [tracking issue template] when creating a tracking issue. 38 | 39 | Larger features should also get a new label in the issue tracker so that when 40 | issues are filed, they can be easily tied together. 41 | 42 | [tracking issue]: https://github.com/rust-lang/cargo/labels/C-tracking-issue 43 | [tracking issue template]: https://github.com/rust-lang/cargo/issues/new?labels=C-tracking-issue&template=tracking_issue.md 44 | 45 | ## Stabilization 46 | 47 | After some period of time, typically measured in months, the feature can be 48 | considered to be stabilized. The feature should not have any significant known 49 | bugs or issues, and any design concerns should be resolved. 50 | 51 | The stabilization process depends on the kind of feature. For smaller 52 | features, you can leave a comment on the tracking issue expressing interest in 53 | stabilizing it. It can usually help to indicate that the feature has received 54 | some real-world testing, and has exhibited some demand for broad use. 55 | 56 | For larger features that have not gone through the [RFC process], then an RFC 57 | to call for stabilization might be warranted. This gives the community a final 58 | chance to provide feedback about the proposed design. 59 | 60 | For a small feature, or one that has already gone through the RFC process, a 61 | Cargo Team member may decide to call for a "final comment period" using 62 | [rfcbot]. This is a public signal that a major change is being made, and gives 63 | the Cargo Team members an opportunity to confirm or block the change. This 64 | process can take a few days or weeks, or longer if a concern is raised. 65 | 66 | Once the stabilization has been approved, the person who called for 67 | stabilization should prepare a PR to stabilize the feature. This PR should: 68 | 69 | * Flip the feature to stable in the [`features` module]. 70 | * Remove any unstable checks that aren't automatically handled by the feature 71 | system. 72 | * Move the documentation from the [unstable chapter] into the appropriate 73 | places in the Cargo book and man pages. 74 | * Remove the `-Z` flags and help message if applicable. 75 | * Update all tests to remove nightly checks. 76 | * Tag the PR with [relnotes] label if it seems important enough to highlight 77 | in the [Rust release notes]. 78 | 79 | [`features` module]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/features.rs 80 | [RFC process]: https://github.com/rust-lang/rfcs/ 81 | [rfcbot]: https://github.com/rust-lang/rfcbot-rs 82 | [Rust release notes]: https://github.com/rust-lang/rust/blob/master/RELEASES.md 83 | [relnotes]: https://github.com/rust-lang/cargo/issues?q=label%3Arelnotes 84 | -------------------------------------------------------------------------------- /contrib/src/architecture/files.md: -------------------------------------------------------------------------------- 1 | # Files 2 | 3 | This chapter gives some pointers on where to start looking at Cargo's on-disk 4 | data file structures. 5 | 6 | * [`Layout`] is the abstraction for the `target` directory. It handles locking 7 | the target directory, and providing paths to the parts inside. There is a 8 | separate `Layout` for each "target". 9 | * [`Resolve`] contains the contents of the `Cargo.lock` file. See the [`encode`] 10 | module for the different `Cargo.lock` formats. 11 | * [`TomlManifest`] contains the contents of the `Cargo.toml` file. It is translated 12 | to a [`Manifest`] object for some simplification, and the `Manifest` is stored 13 | in a [`Package`]. 14 | * The [`fingerprint`] module deals with the fingerprint information stored in 15 | `target/debug/.fingerprint`. This tracks whether or not a crate needs to be 16 | rebuilt. 17 | * `cargo install` tracks its installed files with some metadata in 18 | `$CARGO_HOME`. The metadata is managed in the 19 | [`common_for_install_and_uninstall`] module. 20 | * Git sources are cached in `$CARGO_HOME/git`. The code for this cache is in 21 | the [`git`] source module. 22 | * Registries are cached in `$CARGO_HOME/registry`. There are three parts, the 23 | index, the compressed `.crate` files, and the extracted sources of those 24 | crate files. 25 | * Management of the registry cache can be found in the [`registry`] source 26 | module. Note that this includes an on-disk cache as an optimization for 27 | accessing the git repository. 28 | * Saving of `.crate` files is handled by the [`RemoteRegistry`]. 29 | * Extraction of `.crate` files is handled by the [`RegistrySource`]. 30 | * There is a lock for the package cache. Code must be careful, because 31 | this lock must be obtained manually. See 32 | [`Config::acquire_package_cache_lock`]. 33 | 34 | [`Layout`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/layout.rs 35 | [`Resolve`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/resolve.rs 36 | [`encode`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/resolver/encode.rs 37 | [`TomlManifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/util/toml/mod.rs 38 | [`Manifest`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/manifest.rs 39 | [`Package`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/package.rs 40 | [`common_for_install_and_uninstall`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/common_for_install_and_uninstall.rs 41 | [`git`]: https://github.com/rust-lang/cargo/tree/master/src/cargo/sources/git 42 | [`registry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs 43 | [`RemoteRegistry`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/remote.rs 44 | [`RegistrySource`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/mod.rs 45 | [`Config::acquire_package_cache_lock`]: https://github.com/rust-lang/cargo/blob/e4b65bdc80f2a293447f2f6a808fa7c84bf9a357/src/cargo/util/config/mod.rs#L1261-L1266 46 | 47 | ## Filesystems 48 | 49 | Cargo tends to get run on a very wide array of file systems. Different file 50 | systems can have a wide range of capabilities, and Cargo should strive to do 51 | its best to handle them. Some examples of issues to deal with: 52 | 53 | * Not all file systems support locking. Cargo tries to detect if locking is 54 | supported, and if not, will ignore lock errors. This isn't ideal, but it is 55 | difficult to deal with. 56 | * The [`fs::canonicalize`] function doesn't work on all file systems 57 | (particularly some Windows file systems). If that function is used, there 58 | should be a fallback if it fails. This function will also return `\\?\` 59 | style paths on Windows, which can have some issues (such as some tools not 60 | supporting them, or having issues with relative paths). 61 | * Timestamps can be unreliable. The [`fingerprint`] module has a deeper 62 | discussion of this. One example is that Docker cache layers will erase the 63 | fractional part of the time stamp. 64 | * Symlinks are not always supported, particularly on Windows. 65 | 66 | [`fingerprint`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/core/compiler/fingerprint.rs 67 | [`fs::canonicalize`]: https://doc.rust-lang.org/std/fs/fn.canonicalize.html 68 | -------------------------------------------------------------------------------- /src/SUMMARY.en.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | [Introduction](index.md) 4 | 5 | * [Getting Started](getting-started/index.md) 6 | * [Installation](getting-started/installation.md) 7 | * [First Steps with Cargo](getting-started/first-steps.md) 8 | 9 | * [Cargo Guide](guide/index.md) 10 | * [Why Cargo Exists](guide/why-cargo-exists.md) 11 | * [Creating a New Package](guide/creating-a-new-project.md) 12 | * [Working on an Existing Package](guide/working-on-an-existing-project.md) 13 | * [Dependencies](guide/dependencies.md) 14 | * [Package Layout](guide/project-layout.md) 15 | * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.md) 16 | * [Tests](guide/tests.md) 17 | * [Continuous Integration](guide/continuous-integration.md) 18 | * [Cargo Home](guide/cargo-home.md) 19 | * [Build Cache](guide/build-cache.md) 20 | 21 | * [Cargo Reference](reference/index.md) 22 | * [Specifying Dependencies](reference/specifying-dependencies.md) 23 | * [Overriding Dependencies](reference/overriding-dependencies.md) 24 | * [The Manifest Format](reference/manifest.md) 25 | * [Cargo Targets](reference/cargo-targets.md) 26 | * [Workspaces](reference/workspaces.md) 27 | * [Features](reference/features.md) 28 | * [Features Examples](reference/features-examples.md) 29 | * [Profiles](reference/profiles.md) 30 | * [Configuration](reference/config.md) 31 | * [Environment Variables](reference/environment-variables.md) 32 | * [Build Scripts](reference/build-scripts.md) 33 | * [Build Script Examples](reference/build-script-examples.md) 34 | * [Publishing on crates.io](reference/publishing.md) 35 | * [Package ID Specifications](reference/pkgid-spec.md) 36 | * [Source Replacement](reference/source-replacement.md) 37 | * [External Tools](reference/external-tools.md) 38 | * [Registries](reference/registries.md) 39 | * [Dependency Resolution](reference/resolver.md) 40 | * [SemVer Compatibility](reference/semver.md) 41 | * [Future incompat report](reference/future-incompat-report.md) 42 | * [Unstable Features](reference/unstable.md) 43 | 44 | * [Cargo Commands](commands/index.md) 45 | * [General Commands](commands/general-commands.md) 46 | * [cargo](commands/cargo.md) 47 | * [cargo help](commands/cargo-help.md) 48 | * [cargo version](commands/cargo-version.md) 49 | * [Build Commands](commands/build-commands.md) 50 | * [cargo bench](commands/cargo-bench.md) 51 | * [cargo build](commands/cargo-build.md) 52 | * [cargo check](commands/cargo-check.md) 53 | * [cargo clean](commands/cargo-clean.md) 54 | * [cargo doc](commands/cargo-doc.md) 55 | * [cargo fetch](commands/cargo-fetch.md) 56 | * [cargo fix](commands/cargo-fix.md) 57 | * [cargo run](commands/cargo-run.md) 58 | * [cargo rustc](commands/cargo-rustc.md) 59 | * [cargo rustdoc](commands/cargo-rustdoc.md) 60 | * [cargo test](commands/cargo-test.md) 61 | * [cargo report](commands/cargo-report.md) 62 | * [Manifest Commands](commands/manifest-commands.md) 63 | * [cargo generate-lockfile](commands/cargo-generate-lockfile.md) 64 | * [cargo locate-project](commands/cargo-locate-project.md) 65 | * [cargo metadata](commands/cargo-metadata.md) 66 | * [cargo pkgid](commands/cargo-pkgid.md) 67 | * [cargo tree](commands/cargo-tree.md) 68 | * [cargo update](commands/cargo-update.md) 69 | * [cargo vendor](commands/cargo-vendor.md) 70 | * [cargo verify-project](commands/cargo-verify-project.md) 71 | * [Package Commands](commands/package-commands.md) 72 | * [cargo init](commands/cargo-init.md) 73 | * [cargo install](commands/cargo-install.md) 74 | * [cargo new](commands/cargo-new.md) 75 | * [cargo search](commands/cargo-search.md) 76 | * [cargo uninstall](commands/cargo-uninstall.md) 77 | * [Publishing Commands](commands/publishing-commands.md) 78 | * [cargo login](commands/cargo-login.md) 79 | * [cargo owner](commands/cargo-owner.md) 80 | * [cargo package](commands/cargo-package.md) 81 | * [cargo publish](commands/cargo-publish.md) 82 | * [cargo yank](commands/cargo-yank.md) 83 | 84 | * [FAQ](faq.md) 85 | * [Appendix: Glossary](appendix/glossary.md) 86 | * [Appendix: Git Authentication](appendix/git-authentication.md) 87 | -------------------------------------------------------------------------------- /src/commands/cargo-login.zh.md: -------------------------------------------------------------------------------- 1 | # cargo-login(1) 2 | 3 | ## NAME 4 | 5 | Cargo登录-从注册表本地保存API令牌 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo login` [*options*][_token_] 10 | 11 | ## DESCRIPTION 12 | 13 | 此命令将API令牌保存到磁盘，以便需要身份验证的命令，例如[cargo-publish(1)](cargo-publish.html)，将自动进行身份验证。令牌保存在`$CARGO_HOME/credentials.toml`. `CARGO_HOME`默认为`.cargo`在你的主目录中。 14 | 15 | 如果*代币*未指定参数，将从stdin读取。 16 | 17 | 箱子的API标记。io可以从. 18 | 19 | 注意对代币保密，不得与他人分享。 20 | 21 | ## OPTIONS 22 | 23 | ### Login Options 24 | 25 |
26 |
--registry registry
27 |
Name of the registry to use. Registry names are defined in Cargo config 28 | files. If not specified, the default registry is used, 29 | which is defined by the registry.default config key which defaults to 30 | crates-io.
31 | 32 |
33 | 34 | ### Display Options 35 | 36 |
37 |
-v
38 |
--verbose
39 |
Use verbose output. May be specified twice for "very verbose" output which 40 | includes extra output such as dependency warnings and build script output. 41 | May also be specified with the term.verbose 42 | config value.
43 | 44 |
-q
45 |
--quiet
46 |
Do not print cargo log messages. 47 | May also be specified with the term.quiet 48 | config value.
49 | 50 |
--color when
51 |
Control when colored output is used. Valid values:

52 |
    53 |
  • auto (default): Automatically detect if color support is available on the 54 | terminal.
    • 55 |
  • always: Always display colors.
    • 56 |
  • never: Never display colors.
    • 57 |
58 |

May also be specified with the term.color 59 | config value.

60 | 61 |
62 | 63 | ### Common Options 64 | 65 |
66 | 67 |
+toolchain
68 |
If Cargo has been installed with rustup, and the first argument to cargo 69 | begins with +, it will be interpreted as a rustup toolchain name (such 70 | as +stable or +nightly). 71 | See the rustup documentation 72 | for more information about how toolchain overrides work.
73 | 74 |
-h
75 |
--help
76 |
Prints help information.
77 | 78 |
-Z flag
79 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
80 | 81 |
82 | 83 | ## ENVIRONMENT 84 | 85 | 查看[the reference](../reference/environment-variables.html)有关Cargo读取的环境变量的详细信息。 86 | 87 | ## EXIT STATUS 88 | 89 | - `0`：Cargo成功。 90 | - `101`：Cargo未能完成。 91 | 92 | ## EXAMPLES 93 | 94 | 1. 将API令牌保存到磁盘： 95 | 96 | Cargo登录 97 | 98 | ## SEE ALSO 99 | 100 | [cargo(1)](cargo.zh.md), [cargo-publish(1)](cargo-publish.html) 101 | -------------------------------------------------------------------------------- /src/reference/config.zh.md: -------------------------------------------------------------------------------- 1 | ## 配置 2 | 3 | 本文档将解释 Cargo 的配置系统如何工作，以及可用的字段或配置。有关通过其清单，来配置程序包的信息，请参阅[清单格式](./manifest.zh.md). 4 | 5 | ### Hierarchical structure 6 | 7 | 分层策略 8 | 9 | Cargo 允许特定包，具有本地配置以及全局配置，就像 git 一样。Cargo 将其扩展为分层策略。例如，如果在`/projects/foo/bar/baz`调用 Cargo，然后将按以下顺序，探测和统一配置文件: 10 | 11 | - `/projects/foo/bar/baz/.cargo/config` 12 | - `/projects/foo/bar/.cargo/config` 13 | - `/projects/foo/.cargo/config` 14 | - `/projects/.cargo/config` 15 | - `/.cargo/config` 16 | - `$HOME/.cargo/config` 17 | 18 | 使用此结构，您可以为每个包指定配置，甚至可以将其检入版本控制。您还可以在主目录中，使用指定默认值的配置文件。 19 | 20 | ### Configuration format 21 | 22 | 配置格式 23 | 24 | 所有配置目前都在[TOML 格式][toml](与 Cargo.toml 清单一样)，在字段(表格)内部使用简单的键值对，它们都被合并在一起。 25 | 26 | [toml]: https://github.com/toml-lang/toml 27 | 28 | ### Configuration keys 29 | 30 | 配置字段 31 | 32 | 以下所有字段都是可选的，除非另有说明，否则它们的默认值将作为其值。 33 | 34 | 指定工具的键值可以给出，一个‘绝对路径，相对路径或无路径工具名称’。给定的绝对路径和无路径工具名称直接使用。相对路径，则解析相对于`.cargo`目录的父目录，配置文件就居住在里面。 35 | 36 | ```bash 37 | # 路径数组，指向本地将要覆盖依赖项的存储库. 38 | # 更多信息，请看 指定 依赖项 指南. 39 | paths = ["/path/to/override"] 40 | 41 | [cargo-new] 42 | # 这是你 放 name/email 的地方， 在一个新Cargo.toml中的 43 | #`authors` 表格就会生成。若不存在， 那 `git` 会去调查， 若还是不 44 | # 存在，那 `$USER` 和 `$EMAIL` 会被使用. 45 | name = "..." 46 | email = "..." 47 | 48 | # 默认来说， `cargo new` 会初始化一个新的 Git repository. 该字段若设为 `hg` ，就是新建一个 Mercurial repository， 或 `none` 禁用此行为. 49 | vcs = "none" 50 | 51 | # 接下来的 部分， $triple 是 一些有效目标 triple的引用， 而不是一个字面量"$triple"的意思， 这个引用是无论何时都能应用编译的。 52 | # 'cfg(...)' 是参考 类Rust `#[cfg]` 语法 (条件语句) 53 | [target.$triple] 54 | # linker 可传递参数给 rustc (通过 `-C linker=`) 当 `$triple` 55 | # 要被编译. 默认不传递东东 56 | linker = ".." 57 | # 一样，但这是传递给 rustc 关于 库压缩的参数 ，通过 `-C ar=`. 58 | ar = ".." 59 | # 若 提供了 一个 runner ， 编译`$triple`目标 会通过 执行 runner 执行文件来完成， 它会将真正的目标 作为第一参数. 60 | # 这可运行 `cargo run`， `cargo test` 和 `cargo bench` 命令. 61 | # 默认，编译目标是 直接执行的. 62 | runner = ".." 63 | # 自定义 全编译器，目标为 $triple 64 | # 这些值会覆盖 build.rustflags 65 | rustflags = ["..", ".."] 66 | 67 | [target.'cfg(...)'] 68 | # 与 $triple 配置类似， 但使用的是 `cfg` 语法. 69 | # 若有几个 `cfg` 和 $triple 目标作为备用， 那 rustflags 70 | # 会被串联起来. 该 `cfg` 语法仅能应用到 rustflags， 而不能是 71 | # linker. 72 | rustflags = ["..", ".."] 73 | # 与 $triple 配置类似 ， 但使用的是 `cfg` 语法. 74 | # 若 一个或多个 `cfg`s， 和一个 a $triple 目标作为备用，那 该$triple将会被使用 75 | # 若有几个 `cfg` 和 备用的， 那构建会 error 76 | runner = ".." 77 | 78 | # 关联到 注册表 的配置字段 79 | [registry] 80 | index = "..." # 注册表索引的URL（默认为中央存储库） 81 | token = "..." # 访问令牌（在中央回购网站上找到） 82 | default = "..." # 要使用的默认备用注册表（可以使用--registry覆盖） 83 | 84 | [http] 85 | proxy = "host:port" # 用于HTTP请求的HTTP代理（默认为none） 86 | # libcurl格式，例如“socks5h://host:port” 87 | timeout = 30 # 每个HTTP请求的超时，以秒为单位 88 | cainfo = "cert.pem" # 证书颁发机构（CA）包的路径（可选） 89 | check-revoke = true # 指示是否检查SSL证书是否已废除 90 | low-speed-limit = 5 # 限速 字节/秒（10 = 默认值，0 = 禁用） 91 | multiplexing = true # 是否在可能的情况下使用 HTTP/2多路复用 92 | 93 | # 此设置可用于帮助调试Cargo所发生的HTTP请求 94 | # 当设置为“true”时，将填充Cargo的正常调试日志记录 95 | # 关于HTTP的信息，您可以使用 96 | # `RUST_LOG=cargo::ops::registry=debug`提取（和`trace`可能会打印更多）。 97 | # 98 | # 在将这些日志发布到其他地方时要小心，因可能存在这样的 99 | # header中，有一个你不想泄露的身份验证令牌的情况！务必 100 | # 在发布之前简要查看日志。 101 | debug = false 102 | 103 | [build] 104 | jobs = 1 # 并行作业数，默认为CPU数 105 | rustc = "rustc" # rust编译器工具 106 | rustdoc = "rustdoc" # doc生成器工具 107 | target = "triple" # build为目标 triple（被`cargo install`忽略） 108 | target-dir = "target" # 放置所有生成的工件的路径 109 | rustflags = ["..", ".."] # 自定义 传递给所有编译器调用 的参数 110 | incremental = true # 是否启用增量编译 111 | dep-info-basedir = ".." # depfiles中，目标的基本目录的完整路径 112 | 113 | [term] 114 | verbose = false # Cargo否提供详细输出 115 | color = 'auto' # Cargo否着色输出 116 | 117 | # 网络配置 118 | [net] 119 | retry = 2 # 失败 自动重试 次数 120 | git-fetch-with-cli = false # 若为 `true` 我们会使用 `git`命令行去 fetch git repos 121 | 122 | # 别名 cargo 命令. 前 3 个aliases 是内置的. 如果你的命令 要求 整行命令，请使用 list 格式. 123 | [alias] 124 | b = "build" 125 | t = "test" 126 | r = "run" 127 | rr = "run --release" 128 | space_example = ["run", "--release", "--", "\"command list\""] 129 | ``` 130 | 131 | ### Environment variables 132 | 133 | 环境变量 134 | 135 | 除了上面的 TOML 语法之外，还可以通过环境变量配置 Cargo。对于上方的`foo.bar`表格的每个配置字段，也可以用环境变量`CARGO_FOO_BAR`来定义值。比如说`build.jobs`字段，也可以通过`CARGO_BUILD_JOBS`定义。 136 | 137 | 环境变量将优先于 TOML 配置，并且当前仅支持由环境变量定义的整数，布尔和字符串字段，这意味着[来源更换][source]，能由表格表示，却不能通过环境变量配置。 138 | 139 | 除上述系统外，Cargo 还认可其他一些特定的[环境变量][env]. 140 | 141 | [env]: ./environment-variables.zh.md 142 | [source]: ./source-replacement.zh.md 143 | -------------------------------------------------------------------------------- /src/guide/cargo-toml-vs-cargo-lock.md: -------------------------------------------------------------------------------- 1 | ## Cargo.toml vs Cargo.lock 2 | 3 | `Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk 4 | about them, here’s a summary: 5 | 6 | * `Cargo.toml` is about describing your dependencies in a broad sense, and is 7 | written by you. 8 | * `Cargo.lock` contains exact information about your dependencies. It is 9 | maintained by Cargo and should not be manually edited. 10 | 11 | If you’re building a non-end product, such as a rust library that other rust 12 | [packages][def-package] will depend on, put `Cargo.lock` in your 13 | `.gitignore`. If you’re building an end product, which are executable like 14 | command-line tool or an application, or a system library with crate-type of 15 | `staticlib` or `cdylib`, check `Cargo.lock` into `git`. If you're curious 16 | about why that is, see 17 | ["Why do binaries have `Cargo.lock` in version control, but not libraries?" in the 18 | FAQ](../faq.md#why-do-binaries-have-cargolock-in-version-control-but-not-libraries). 19 | 20 | Let’s dig in a little bit more. 21 | 22 | `Cargo.toml` is a [**manifest**][def-manifest] file in which we can specify a 23 | bunch of different metadata about our package. For example, we can say that we 24 | depend on another package: 25 | 26 | ```toml 27 | [package] 28 | name = "hello_world" 29 | version = "0.1.0" 30 | 31 | [dependencies] 32 | regex = { git = "https://github.com/rust-lang/regex.git" } 33 | ``` 34 | 35 | This package has a single dependency, on the `regex` library. We’ve stated in 36 | this case that we’re relying on a particular Git repository that lives on 37 | GitHub. Since we haven’t specified any other information, Cargo assumes that 38 | we intend to use the latest commit on the `master` branch to build our package. 39 | 40 | Sound good? Well, there’s one problem: If you build this package today, and 41 | then you send a copy to me, and I build this package tomorrow, something bad 42 | could happen. There could be more commits to `regex` in the meantime, and my 43 | build would include new commits while yours would not. Therefore, we would 44 | get different builds. This would be bad because we want reproducible builds. 45 | 46 | We could fix this problem by putting a `rev` line in our `Cargo.toml`: 47 | 48 | ```toml 49 | [dependencies] 50 | regex = { git = "https://github.com/rust-lang/regex.git", rev = "9f9f693" } 51 | ``` 52 | 53 | Now our builds will be the same. But there’s a big drawback: now we have to 54 | manually think about SHA-1s every time we want to update our library. This is 55 | both tedious and error prone. 56 | 57 | Enter the `Cargo.lock`. Because of its existence, we don’t need to manually 58 | keep track of the exact revisions: Cargo will do it for us. When we have a 59 | manifest like this: 60 | 61 | ```toml 62 | [package] 63 | name = "hello_world" 64 | version = "0.1.0" 65 | 66 | [dependencies] 67 | regex = { git = "https://github.com/rust-lang/regex.git" } 68 | ``` 69 | 70 | Cargo will take the latest commit and write that information out into our 71 | `Cargo.lock` when we build for the first time. That file will look like this: 72 | 73 | ```toml 74 | [[package]] 75 | name = "hello_world" 76 | version = "0.1.0" 77 | dependencies = [ 78 | "regex 1.5.0 (git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c586c33ed3a6831)", 79 | ] 80 | 81 | [[package]] 82 | name = "regex" 83 | version = "1.5.0" 84 | source = "git+https://github.com/rust-lang/regex.git#9f9f693768c584971a4d53bc3c586c33ed3a6831" 85 | ``` 86 | 87 | You can see that there’s a lot more information here, including the exact 88 | revision we used to build. Now when you give your package to someone else, 89 | they’ll use the exact same SHA, even though we didn’t specify it in our 90 | `Cargo.toml`. 91 | 92 | When we’re ready to opt in to a new version of the library, Cargo can 93 | re-calculate the dependencies and update things for us: 94 | 95 | ```console 96 | $ cargo update # updates all dependencies 97 | $ cargo update -p regex # updates just “regex” 98 | ``` 99 | 100 | This will write out a new `Cargo.lock` with the new version information. Note 101 | that the argument to `cargo update` is actually a 102 | [Package ID Specification](../reference/pkgid-spec.md) and `regex` is just a 103 | short specification. 104 | 105 | [def-manifest]: ../appendix/glossary.md#manifest '"manifest" (glossary entry)' 106 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 107 | -------------------------------------------------------------------------------- /src/guide/cargo-home.md: -------------------------------------------------------------------------------- 1 | ## Cargo Home 2 | 3 | The "Cargo home" functions as a download and source cache. 4 | When building a [crate][def-crate], Cargo stores downloaded build dependencies in the Cargo home. 5 | You can alter the location of the Cargo home by setting the `CARGO_HOME` [environmental variable][env]. 6 | The [home](https://crates.io/crates/home) crate provides an API for getting this location if you need this information inside your Rust crate. 7 | By default, the Cargo home is located in `$HOME/.cargo/`. 8 | 9 | Please note that the internal structure of the Cargo home is not stabilized and may be subject to change at any time. 10 | 11 | The Cargo home consists of following components: 12 | 13 | ## Files: 14 | 15 | * `config.toml` 16 | Cargo's global configuration file, see the [config entry in the reference][config]. 17 | 18 | * `credentials.toml` 19 | Private login credentials from [`cargo login`] in order to log in to a [registry][def-registry]. 20 | 21 | * `.crates.toml`, `.crates2.json` 22 | These hidden files contain [package][def-package] information of crates installed via [`cargo install`]. Do NOT edit by hand! 23 | 24 | ## Directories: 25 | 26 | * `bin` 27 | The bin directory contains executables of crates that were installed via [`cargo install`] or [`rustup`](https://rust-lang.github.io/rustup/). 28 | To be able to make these binaries accessible, add the path of the directory to your `$PATH` environment variable. 29 | 30 | * `git` 31 | Git sources are stored here: 32 | 33 | * `git/db` 34 | When a crate depends on a git repository, Cargo clones the repo as a bare repo into this directory and updates it if necessary. 35 | 36 | * `git/checkouts` 37 | If a git source is used, the required commit of the repo is checked out from the bare repo inside `git/db` into this directory. 38 | This provides the compiler with the actual files contained in the repo of the commit specified for that dependency. 39 | Multiple checkouts of different commits of the same repo are possible. 40 | 41 | * `registry` 42 | Packages and metadata of crate registries (such as [crates.io](https://crates.io/)) are located here. 43 | 44 | * `registry/index` 45 | The index is a bare git repository which contains the metadata (versions, dependencies etc) of all available crates of a registry. 46 | 47 | * `registry/cache` 48 | Downloaded dependencies are stored in the cache. The crates are compressed gzip archives named with a `.crate` extension. 49 | 50 | * `registry/src` 51 | If a downloaded `.crate` archive is required by a package, it is unpacked into `registry/src` folder where rustc will find the `.rs` files. 52 | 53 | 54 | ## Caching the Cargo home in CI 55 | 56 | To avoid redownloading all crate dependencies during continuous integration, you can cache the `$CARGO_HOME` directory. 57 | However, caching the entire directory is often inefficient as it will contain downloaded sources twice. 58 | If we depend on a crate such as `serde 1.0.92` and cache the entire `$CARGO_HOME` we would actually cache the sources twice, the `serde-1.0.92.crate` inside `registry/cache` and the extracted `.rs` files of serde inside `registry/src`. 59 | That can unnecessarily slow down the build as downloading, extracting, recompressing and reuploading the cache to the CI servers can take some time. 60 | 61 | It should be sufficient to only cache the following directories across builds: 62 | 63 | * `bin/` 64 | * `registry/index/` 65 | * `registry/cache/` 66 | * `git/db/` 67 | 68 | 69 | 70 | ## Vendoring all dependencies of a project 71 | 72 | See the [`cargo vendor`] subcommand. 73 | 74 | 75 | 76 | ## Clearing the cache 77 | 78 | In theory, you can always remove any part of the cache and Cargo will do its best to restore sources if a crate needs them either by reextracting an archive or checking out a bare repo or by simply redownloading the sources from the web. 79 | 80 | Alternatively, the [cargo-cache](https://crates.io/crates/cargo-cache) crate provides a simple CLI tool to only clear selected parts of the cache or show sizes of its components in your command-line. 81 | 82 | [`cargo install`]: ../commands/cargo-install.md 83 | [`cargo login`]: ../commands/cargo-login.md 84 | [`cargo vendor`]: ../commands/cargo-vendor.md 85 | [config]: ../reference/config.md 86 | [def-crate]: ../appendix/glossary.md#crate '"crate" (glossary entry)' 87 | [def-package]: ../appendix/glossary.md#package '"package" (glossary entry)' 88 | [def-registry]: ../appendix/glossary.md#registry '"registry" (glossary entry)' 89 | [env]: ../reference/environment-variables.md 90 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | [Introduction](index.zh.md) 4 | 5 | * [Getting Started](getting-started/index.zh.md) 6 | * [Installation](getting-started/installation.zh.md) 7 | * [First Steps with Cargo](getting-started/first-steps.zh.md) 8 | 9 | * [Cargo Guide](guide/index.zh.md) 10 | * [Why Cargo Exists](guide/why-cargo-exists.zh.md) 11 | * [Creating a New Package](guide/creating-a-new-project.zh.md) 12 | * [Working on an Existing Package](guide/working-on-an-existing-project.zh.md) 13 | * [Dependencies](guide/dependencies.zh.md) 14 | * [Package Layout](guide/project-layout.zh.md) 15 | * [Cargo.toml vs Cargo.lock](guide/cargo-toml-vs-cargo-lock.zh.md) 16 | * [Tests](guide/tests.zh.md) 17 | * [Continuous Integration](guide/continuous-integration.zh.md) 18 | * [Cargo Home](guide/cargo-home.zh.md) 19 | * [Build Cache](guide/build-cache.zh.md) 20 | 21 | * [Cargo Reference](reference/index.zh.md) 22 | * [Specifying Dependencies](reference/specifying-dependencies.zh.md) 23 | * [Overriding Dependencies](reference/overriding-dependencies.zh.md) 24 | * [The Manifest Format](reference/manifest.zh.md) 25 | * [Cargo Targets](reference/cargo-targets.zh.md) 26 | * [Workspaces](reference/workspaces.zh.md) 27 | * [Features](reference/features.zh.md) 28 | * [Features Examples](reference/features-examples.zh.md) 29 | * [Profiles](reference/profiles.zh.md) 30 | * [Configuration](reference/config.zh.md) 31 | * [Environment Variables](reference/environment-variables.zh.md) 32 | * [Build Scripts](reference/build-scripts.zh.md) 33 | * [Build Script Examples](reference/build-script-examples.zh.md) 34 | * [Publishing on crates.io](reference/publishing.zh.md) 35 | * [Package ID Specifications](reference/pkgid-spec.zh.md) 36 | * [Source Replacement](reference/source-replacement.zh.md) 37 | * [External Tools](reference/external-tools.zh.md) 38 | * [Registries](reference/registries.zh.md) 39 | * [Dependency Resolution](reference/resolver.zh.md) 40 | * [SemVer Compatibility](reference/semver.zh.md) 41 | * [Future incompat report](reference/future-incompat-report.zh.md) 42 | * [Unstable Features](reference/unstable.zh.md) 43 | 44 | * [Cargo Commands](commands/index.zh.md) 45 | * [General Commands](commands/general-commands.zh.md) 46 | * [cargo](commands/cargo.zh.md) 47 | * [cargo help](commands/cargo-help.zh.md) 48 | * [cargo version](commands/cargo-version.zh.md) 49 | * [Build Commands](commands/build-commands.zh.md) 50 | * [cargo bench](commands/cargo-bench.zh.md) 51 | * [cargo build](commands/cargo-build.zh.md) 52 | * [cargo check](commands/cargo-check.zh.md) 53 | * [cargo clean](commands/cargo-clean.zh.md) 54 | * [cargo doc](commands/cargo-doc.zh.md) 55 | * [cargo fetch](commands/cargo-fetch.zh.md) 56 | * [cargo fix](commands/cargo-fix.zh.md) 57 | * [cargo run](commands/cargo-run.zh.md) 58 | * [cargo rustc](commands/cargo-rustc.zh.md) 59 | * [cargo rustdoc](commands/cargo-rustdoc.zh.md) 60 | * [cargo test](commands/cargo-test.zh.md) 61 | * [cargo report](commands/cargo-report.zh.md) 62 | * [Manifest Commands](commands/manifest-commands.zh.md) 63 | * [cargo generate-lockfile](commands/cargo-generate-lockfile.zh.md) 64 | * [cargo locate-project](commands/cargo-locate-project.zh.md) 65 | * [cargo metadata](commands/cargo-metadata.zh.md) 66 | * [cargo pkgid](commands/cargo-pkgid.zh.md) 67 | * [cargo tree](commands/cargo-tree.zh.md) 68 | * [cargo update](commands/cargo-update.zh.md) 69 | * [cargo vendor](commands/cargo-vendor.zh.md) 70 | * [cargo verify-project](commands/cargo-verify-project.zh.md) 71 | * [Package Commands](commands/package-commands.zh.md) 72 | * [cargo init](commands/cargo-init.zh.md) 73 | * [cargo install](commands/cargo-install.zh.md) 74 | * [cargo new](commands/cargo-new.zh.md) 75 | * [cargo search](commands/cargo-search.zh.md) 76 | * [cargo uninstall](commands/cargo-uninstall.zh.md) 77 | * [Publishing Commands](commands/publishing-commands.zh.md) 78 | * [cargo login](commands/cargo-login.zh.md) 79 | * [cargo owner](commands/cargo-owner.zh.md) 80 | * [cargo package](commands/cargo-package.zh.md) 81 | * [cargo publish](commands/cargo-publish.zh.md) 82 | * [cargo yank](commands/cargo-yank.zh.md) 83 | 84 | * [FAQ](faq.zh.md) 85 | * [Appendix: Glossary](appendix/glossary.zh.md) 86 | * [Appendix: Git Authentication](appendix/git-authentication.zh.md) 87 | -------------------------------------------------------------------------------- /docs/fonts/SOURCE-CODE-PRO-LICENSE.txt: -------------------------------------------------------------------------------- 1 | Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries. 2 | 3 | This Font Software is licensed under the SIL Open Font License, Version 1.1. 4 | This license is copied below, and is also available with a FAQ at: 5 | http://scripts.sil.org/OFL 6 | 7 | 8 | ----------------------------------------------------------- 9 | SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007 10 | ----------------------------------------------------------- 11 | 12 | PREAMBLE 13 | The goals of the Open Font License (OFL) are to stimulate worldwide 14 | development of collaborative font projects, to support the font creation 15 | efforts of academic and linguistic communities, and to provide a free and 16 | open framework in which fonts may be shared and improved in partnership 17 | with others. 18 | 19 | The OFL allows the licensed fonts to be used, studied, modified and 20 | redistributed freely as long as they are not sold by themselves. The 21 | fonts, including any derivative works, can be bundled, embedded, 22 | redistributed and/or sold with any software provided that any reserved 23 | names are not used by derivative works. The fonts and derivatives, 24 | however, cannot be released under any other type of license. The 25 | requirement for fonts to remain under this license does not apply 26 | to any document created using the fonts or their derivatives. 27 | 28 | DEFINITIONS 29 | "Font Software" refers to the set of files released by the Copyright 30 | Holder(s) under this license and clearly marked as such. This may 31 | include source files, build scripts and documentation. 32 | 33 | "Reserved Font Name" refers to any names specified as such after the 34 | copyright statement(s). 35 | 36 | "Original Version" refers to the collection of Font Software components as 37 | distributed by the Copyright Holder(s). 38 | 39 | "Modified Version" refers to any derivative made by adding to, deleting, 40 | or substituting -- in part or in whole -- any of the components of the 41 | Original Version, by changing formats or by porting the Font Software to a 42 | new environment. 43 | 44 | "Author" refers to any designer, engineer, programmer, technical 45 | writer or other person who contributed to the Font Software. 46 | 47 | PERMISSION & CONDITIONS 48 | Permission is hereby granted, free of charge, to any person obtaining 49 | a copy of the Font Software, to use, study, copy, merge, embed, modify, 50 | redistribute, and sell modified and unmodified copies of the Font 51 | Software, subject to the following conditions: 52 | 53 | 1) Neither the Font Software nor any of its individual components, 54 | in Original or Modified Versions, may be sold by itself. 55 | 56 | 2) Original or Modified Versions of the Font Software may be bundled, 57 | redistributed and/or sold with any software, provided that each copy 58 | contains the above copyright notice and this license. These can be 59 | included either as stand-alone text files, human-readable headers or 60 | in the appropriate machine-readable metadata fields within text or 61 | binary files as long as those fields can be easily viewed by the user. 62 | 63 | 3) No Modified Version of the Font Software may use the Reserved Font 64 | Name(s) unless explicit written permission is granted by the corresponding 65 | Copyright Holder. This restriction only applies to the primary font name as 66 | presented to the users. 67 | 68 | 4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font 69 | Software shall not be used to promote, endorse or advertise any 70 | Modified Version, except to acknowledge the contribution(s) of the 71 | Copyright Holder(s) and the Author(s) or with their explicit written 72 | permission. 73 | 74 | 5) The Font Software, modified or unmodified, in part or in whole, 75 | must be distributed entirely under this license, and must not be 76 | distributed under any other license. The requirement for fonts to 77 | remain under this license does not apply to any document created 78 | using the Font Software. 79 | 80 | TERMINATION 81 | This license becomes null and void if any of the above conditions are 82 | not met. 83 | 84 | DISCLAIMER 85 | THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 86 | EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF 87 | MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT 88 | OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE 89 | COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 90 | INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL 91 | DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 92 | FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM 93 | OTHER DEALINGS IN THE FONT SOFTWARE. 94 | -------------------------------------------------------------------------------- /src/faq.zh.md: -------------------------------------------------------------------------------- 1 | ## Frequently Asked Questions 2 | 3 | 常问问题 4 | 5 | ### Is the plan to use GitHub as a package repository? 6 | 7 | > 是否有计划，使用 Github 作为一个包库 ？ 8 | 9 | 不，Cargo 的计划是使用[crates.io]，像 NPM 或 RuuGuMes 对应 npmjs.org 和 rubygems.org。 10 | 11 | 我们计划永远（通过些配置）支持 git 存储库作为包的来源，因为它们可以用于早期开发和临时补丁（加了点灵活性），即便人们使用主要使用注册表作为包的来源。 12 | 13 | ### Why build crates.io rather than use GitHub as a registry? 14 | 15 | > 为啥，选 crates.io，而不是使用 Github 作为 注册表 ？ 16 | 17 | 我们认为支持多种下载包的方式非常重要，包括从 GitHub 下载包，并将包复制到包本身. 18 | 19 | 也就是说，我们认为[crates.io]提供了许多重要的好处，并且预计其会成为人们在 Cargo 中，下载包的主要方式。 20 | 21 | 前车之鉴，Node.js 的[npm][1]和 Ruby 的[bundler][2]都支持中央注册中心模式，和基于 Git 的模式，而大多数包都是通过生态系统中的注册中心下载的，其中重要的少数包是使用基于 git 的包。 22 | 23 | [1]: https://www.npmjs.org 24 | [2]: https://bundler.io 25 | 26 | 使中央注册中心，在其他语言中流行的一些优点包括: 27 | 28 | - **可发现性**. 中央注册表提供了查找现有包的简单方式。结合标记(版本)，这也使得注册中心能够提供生态系统的范围信息，例如最流行或最依赖的包的列表. 29 | - **速度**. 中心注册中心使得可以快速有效地只获取包的元数据，然后只高效地下载已发布的包，而不会出现在存储库中的其他膨胀。这大大提高了依赖性解析和获取的速度。要知道随着依赖关系图的扩展，下载所有的 git 存储库会陷入困境。还要记住的是，并不是每个人都有高速、低延迟的互联网连接. 30 | 31 | ### Will Cargo work with C code (or other languages)? 32 | 33 | > Cargo 可与 C 语言代码(或其他语言)一起工作吗? 34 | 35 | 可以的! 36 | 37 | Cargo 处理编译 Rust 代码，但我们知道许多 Rust 包与 C 代码都有链接。我们还知道除 Rust 之外，在编译语言方面的工具，已建立了数十年。 38 | 39 | 我们的解决方案:Cargo 允许一个包可以[指定脚本](./build-scripts.zh.md)(用 Rust 编写)，其在调用`rustc`之前运行。 利用 Rust 实现特定于平台的配置和重构包之间的常见构建功能。 40 | 41 | ### Can Cargo be used inside of `make` (or `ninja`, or ...) 42 | 43 | > Cargo 能被用在 `make`(或 `ninja`或...) 中吗 ? 44 | 45 | 当然能。尽管我们希望， Cargo 是作为顶级编译 Rust 包的独立方式，但我们知道有些人希望从其他构建工具调用 Cargo。 46 | 47 | 我们已将 Cargo 设计成在这些环境中工作良好，并注意错误代码和机器可读输出模式等事项。在这些方面我们还有一些工作要做，但是在传统脚本上下文中使用 Cargo 是我们从一开始就设计的，并且将继续优先考虑。 48 | 49 | ### Does Cargo handle multi-platform packages or cross-compilation? 50 | 51 | > Cargo 是怎么平衡 多平台或跨平台的包的？ 52 | 53 | Rust 本身提供了基于平台，配置代码段的工具。Cargo 也支持[特定平台依赖关系][target-deps]，未来，我们计划为每个平台`Cargo.toml`支持更多的配置. 54 | 55 | [target-deps]: reference/specifying-dependencies.md#platform-specific-dependencies 56 | 57 | 从长远来看，我们正在寻找使用 Cargo 方便地跨编译包的方法. 58 | 59 | ### Does Cargo support environments, like `production` or `test`? 60 | 61 | > Cargo 有没支持像`production` 或 `test`这样的环境？ 62 | 63 | 我们通过使用[profiles][profile]来支持这样的环境: 64 | 65 | [profile]: ./manifest.zh.md#the-profile-sections 66 | 67 | - 特定环境标志(像 开发环境的 `-g --opt-level=0`和生产环境的`--opt-level=3`)。 68 | - 特定环境依赖性(像 测试断言 的`hamcrest`). 69 | - 特定环境变量 `#[cfg]` 70 | - 一个`cargo test`命令 71 | 72 | ### Does Cargo work on Windows? 73 | 74 | > Windows 系统 呢，Cargo 能搞吗？ 75 | 76 | 没问题! 77 | 78 | 所有提交的 Cargo 都需要通过 Windows 上的本地测试套件。但是，如果你发现一个 Windows 问题，我们认为它就是一个 bug，所以[请提出一个问题][3]. 79 | 80 | [3]: https://github.com/rust-lang/cargo/issues 81 | 82 | ### Why do binaries have `Cargo.lock` in version control, but not libraries? 83 | 84 | > 为啥，输出二进制的 Cargo 项目具有`Cargo.lock`，而单输出库的，就没有？ 85 | 86 | 一个`Cargo.lock`文件的目的，是在于成功构建，能描述'世界'的状态。然后，它就能用来，通过确保编译完全相同的依赖项，就能跨任何机器上构建确定性的包。 87 | 88 | 这个属性对于，处在依赖链末端的应用程序和包(二进制文件)是最理想的。因此，建议所有二进制文件都在其`Cargo.lock`内部进行检查. 89 | 90 | 对于单库来说，情况有些不同。库不仅被库开发人员使用，而且被库的任何下游消费者使用。依赖库的用户不会检查库的`Cargo.lock`(即使它存在)。正是如此，库**不**应该对库的所有用户进行确定性地重新编译。 91 | 92 | 如果一个库最终被多个依赖项传递使用，那么很可能只需要该库的一个副本(基于 semver 兼容性的版本)。如果 Cargo 使用了所有的 **依赖项的`Cargo.lock`文件**，那结果就是，使用库的多个副本，甚至可能存在版本冲突。 93 | 94 | 换句话说，库为它们的依赖项指定了 semver 版本，但是不用(无法)看到全部内容。只有像二进制文件这样的最终产品才需要有完整的图，来决定应该使用什么版本的依赖。 95 | 96 | ### Can libraries use `*` as a version for their dependencies? 97 | 98 | > 作为库的项目，可以使用`*`作为它们的依赖的版本号吗? 99 | 100 | **截至 2016 年 1 月 22 日，[crates.io]拒绝通配符`*`依赖约束的所有包(不只是库).** 101 | 102 | 库是*可以*，但严格来说，他们不应该这样做。`*`版本要求，说明了"这将适用于任何版本"，而这永远不会是真的。库应该总是指定它们工作的范围，即使它和"每个 1.x.y 版本"一样。 103 | 104 | ### Why `Cargo.toml`? 105 | 106 | 作为与 Cargo 最频繁的交互之一，为什么要命名配置文件叫`Cargo.toml`的问题不时出现。选择领先的大写—`C`，是为了确保清单与目录清单中的其他类似配置文件组合排序。对文件进行排序时，通常将大写字母放在小写字母之前，确保`Makefile`和`Cargo.toml`文件会放在一起。选择`.toml`结尾是强调文件是[特定的配置文件格式](https://github.com/toml-lang/toml). 107 | 108 | Cargo 不允许其他名称(如`cargo.toml`或`Cargofile`)，来强调如何如何容易识别 Cargo 仓库。在历史上，许多可能的名称选择都导致了混乱，其中一个选项被选择了，而其他选项就被自然而然地遗忘。 109 | 110 | [crates.io]: https://crates.io/ 111 | 112 | ### How can Cargo work offline? 113 | 114 | > Cargo 能 离线 工作吗？ 115 | 116 | Cargo 通常用于网络访问有限，或没有网络访问的情况，如飞机、CI 环境或嵌入大型生产部署中。当 Cargo 试图从网络获取资源时，用户常常感到惊讶，因频繁出现 Cargo 离线工作的请求。 117 | 118 | Cargo 的核心是不会试图访问网络，除非被告知这样做。也就是说，如果没有来自 crates.io、git 存储库或其他网络位置的箱，则 Cargo 永远不会尝试进行网络连接。因此，如果 Cargo 试图接触网络，那是因为它需要获取所需的资源。 119 | 120 | Cargo 还非常积极地缓存信息，保持最小化的网络活动量。例如，它将保证`cargo build`(或类似的)运行到完成，那下一次`cargo build`保证不接触网络，只要`Cargo.toml`在此期间还没有被修改。网络的这种回避归结为，已存在`Cargo.lock`，和在 lock 文件中反映了，箱子的充分缓存。如果这些组件中的任何一个丢失，那么构建的成功就需要它们，并且必须远程获取它们。 121 | 122 | 对 Rust 1.11.0 打后的 Cargo ，可以看到新的(标志)参数`--frozen`，这是它不应该接触网络的断言。当传递给 Cargo，如果 Cargo 试图进行网络请求，它将立即返回一个错误。错误应该包括关于为什么进行网络请求(第一个地方），以帮助调试的上下文信息。注意这个标志是*不改变 Cargo 的行为*，它只是断言 Cargo 不应该触摸网络，这作为上一个命令已完成的保证，可以相同的网络活动是不必的。 123 | 124 | > 上一个命令，如`cargo build` 125 | 126 | 有关版本管理的详细信息，请参阅文档[来源更换][replace]. 127 | 128 | [replace]: ./source-replacement.zh.md 129 | -------------------------------------------------------------------------------- /src/commands/cargo-login.md: -------------------------------------------------------------------------------- 1 | # cargo-login(1) 2 | 3 | ## NAME 4 | 5 | cargo-login - Save an API token from the registry locally 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo login` [_options_] [_token_] 10 | 11 | ## DESCRIPTION 12 | 13 | This command will save the API token to disk so that commands that require 14 | authentication, such as [cargo-publish(1)](cargo-publish.html), will be automatically 15 | authenticated. The token is saved in `$CARGO_HOME/credentials.toml`. `CARGO_HOME` 16 | defaults to `.cargo` in your home directory. 17 | 18 | If the _token_ argument is not specified, it will be read from stdin. 19 | 20 | The API token for crates.io may be retrieved from . 21 | 22 | Take care to keep the token secret, it should not be shared with anyone else. 23 | 24 | ## OPTIONS 25 | 26 | ### Login Options 27 | 28 |
29 |
--registry registry
30 |
Name of the registry to use. Registry names are defined in Cargo config 31 | files. If not specified, the default registry is used, 32 | which is defined by the registry.default config key which defaults to 33 | crates-io.
34 | 35 | 36 |
37 | 38 | ### Display Options 39 | 40 |
41 |
-v
42 |
--verbose
43 |
Use verbose output. May be specified twice for "very verbose" output which 44 | includes extra output such as dependency warnings and build script output. 45 | May also be specified with the term.verbose 46 | config value.
47 | 48 | 49 |
-q
50 |
--quiet
51 |
Do not print cargo log messages. 52 | May also be specified with the term.quiet 53 | config value.
54 | 55 | 56 |
--color when
57 |
Control when colored output is used. Valid values:

58 |
    59 |
  • auto (default): Automatically detect if color support is available on the 60 | terminal.
    • 61 |
  • always: Always display colors.
    • 62 |
  • never: Never display colors.
    • 63 |
64 |

May also be specified with the term.color 65 | config value.

66 | 67 | 68 |
69 | 70 | ### Common Options 71 | 72 |
73 | 74 |
+toolchain
75 |
If Cargo has been installed with rustup, and the first argument to cargo 76 | begins with +, it will be interpreted as a rustup toolchain name (such 77 | as +stable or +nightly). 78 | See the rustup documentation 79 | for more information about how toolchain overrides work.
80 | 81 | 82 |
-h
83 |
--help
84 |
Prints help information.
85 | 86 | 87 |
-Z flag
88 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
89 | 90 | 91 |
92 | 93 | 94 | ## ENVIRONMENT 95 | 96 | See [the reference](../reference/environment-variables.html) for 97 | details on environment variables that Cargo reads. 98 | 99 | 100 | ## EXIT STATUS 101 | 102 | * `0`: Cargo succeeded. 103 | * `101`: Cargo failed to complete. 104 | 105 | 106 | ## EXAMPLES 107 | 108 | 1. Save the API token to disk: 109 | 110 | cargo login 111 | 112 | ## SEE ALSO 113 | [cargo(1)](cargo.zh.md), [cargo-publish(1)](cargo-publish.html) 114 | -------------------------------------------------------------------------------- /src/commands/cargo-search.zh.md: -------------------------------------------------------------------------------- 1 | # cargo-search(1) 2 | 3 | ## NAME 4 | 5 | Cargo搜索——在箱子中搜索包。木卫一 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo search` [*options*][_query_...] 10 | 11 | ## DESCRIPTION 12 | 13 | 这将对机器上的箱子执行文本搜索.匹配的箱子将以适合复制到文件中的TOML格式显示及其说明`Cargo.toml`显示 14 | 15 | ## OPTIONS 16 | 17 | ### Search Options 18 | 19 |
20 | 21 |
--limit limit
22 |
Limit the number of results (default: 10, max: 100).
23 | 24 |
--index index
25 |
The URL of the registry index to use.
26 | 27 |
--registry registry
28 |
Name of the registry to use. Registry names are defined in Cargo config 29 | files. If not specified, the default registry is used, 30 | which is defined by the registry.default config key which defaults to 31 | crates-io.
32 | 33 |
34 | 35 | ### Display Options 36 | 37 |
38 |
-v
39 |
--verbose
40 |
Use verbose output. May be specified twice for "very verbose" output which 41 | includes extra output such as dependency warnings and build script output. 42 | May also be specified with the term.verbose 43 | config value.
44 | 45 |
-q
46 |
--quiet
47 |
Do not print cargo log messages. 48 | May also be specified with the term.quiet 49 | config value.
50 | 51 |
--color when
52 |
Control when colored output is used. Valid values:

53 |
    54 |
  • auto (default): Automatically detect if color support is available on the 55 | terminal.
    • 56 |
  • always: Always display colors.
    • 57 |
  • never: Never display colors.
    • 58 |
59 |

May also be specified with the term.color 60 | config value.

61 | 62 |
63 | 64 | ### Common Options 65 | 66 |
67 | 68 |
+toolchain
69 |
If Cargo has been installed with rustup, and the first argument to cargo 70 | begins with +, it will be interpreted as a rustup toolchain name (such 71 | as +stable or +nightly). 72 | See the rustup documentation 73 | for more information about how toolchain overrides work.
74 | 75 |
-h
76 |
--help
77 |
Prints help information.
78 | 79 |
-Z flag
80 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
81 | 82 |
83 | 84 | ## ENVIRONMENT 85 | 86 | 查看[the reference](../reference/environment-variables.html)有关Cargo读取的环境变量的详细信息。 87 | 88 | ## EXIT STATUS 89 | 90 | - `0`：Cargo成功。 91 | - `101`：Cargo未能完成。 92 | 93 | ## EXAMPLES 94 | 95 | 1. 从箱子中寻找包。io: 96 | 97 | Cargo搜索服务 98 | 99 | ## SEE ALSO 100 | 101 | [cargo(1)](cargo.zh.md), [cargo-install(1)](cargo-install.html), [cargo-publish(1)](cargo-publish.html) 102 | -------------------------------------------------------------------------------- /src/reference/publishing.zh.md: -------------------------------------------------------------------------------- 1 | ## 发布到 crates.io 2 | 3 | 一旦你有一个你想与世界分享的 crate，就该把它发布到[crates.io]! 发布是指，上载特定版本的，以让[crates.io]进行托管. 4 | 5 | 发布箱(crate)子时，要小心，因为发布是**常驻**。永远不能覆盖同版本，并且无法删除代码。但是，可以发布的版本数量没有限制。 6 | 7 | ### 在你开始发布前 8 | 9 | 首先，你需要一个[crates.io]帐户，用来获取 API 令牌。为此，[访问主页][crates.io]，并通过 GitHub 帐户登录(现在需要)。在此之后，访问你的[帐号设定](https://crates.io/me)页面，并运行`cargo login`命令联通账号。 10 | 11 | ```console 12 | $ cargo login abcdefghijklmnopqrstuvwxyz012345 13 | ``` 14 | 15 | 此命令将告诉 Cargo 关于您的 API 令牌，并将其存储在您的本地`~/.cargo/credentials`(以前是`~/.cargo/config`)。请注意，此令牌是一个**秘密**，不应与其他任何人分享。如果因任何原因泄漏，您应立即重新生成。 16 | 17 | ### 在你创建新 crate 前 18 | 19 | 请记住[crates.io]上箱子的名字，会采取先到先得的方式分配。一旦获得箱子名称，它就不能用于另一个箱子. 20 | 21 | #### 打包一个 crate 22 | 23 | 下一步是，将您的包装箱打包成可供[crates.io]上传的格式。为此，我们将使用`cargo package`子命令。这将把我们的整个包装箱全部打包成一个`*.crate`文件，其在`target/package`目录中。 24 | 25 | ```console 26 | $ cargo package 27 | ``` 28 | 29 | 作为一个额外的功能，`*.crate`将独立于当前源树进行验证。在`*.crate`创建之后，会解压到`target/package`目录，然后从头开始构建，以确保构建成功的所有必要文件。可以使用`--no-verify`参数禁用此行为。 30 | 31 | 现在是时候看看`*.crate`文件了，为了确保您不会意外地打包 2GB 视频资源，或用于代码生成，集成测试或基准测试的大型数据文件。目前存在 10MB 的`*.crate`文件上传大小限制。所以，如果`tests`和`benches`目录及其依赖项大小，最多只达 几 MB，您仍可以将它们保存在包; 不然的话，最好排除它们。 32 | 33 | 在打包时，Cargo 会自动忽略版本控制系统的忽略文件，但是如果要指定要额外的忽略文件集，则可以使用清单中的`exclude`字段: 34 | 35 | ```toml 36 | [package] 37 | # ... 38 | exclude = [ 39 | "public/assets/*", 40 | "videos/*", 41 | ] 42 | ``` 43 | 44 | 这个数组中每个元素接受的语法是[rust-lang/glob](https://github.com/rust-lang/glob)。如果您宁愿使用白名单，而不是黑名单,Cargo 也支持`include`字段，如果设置,则会覆盖`exclude`字段: 45 | 46 | ```toml 47 | [package] 48 | # ... 49 | include = [ 50 | "**/*.rs", 51 | "Cargo.toml", 52 | ] 53 | ``` 54 | 55 | ### 上传该 crate 56 | 57 | 现在我们已经有了`*.crate`文件准备好了，可以上传到[crates.io]，接着使用`cargo publish`命令就好。就是这样，你现在已经发布了你的第一个箱子! 58 | 59 | ```console 60 | $ cargo publish 61 | ``` 62 | 63 | 如果你想跳过`cargo package`那一步，`cargo publish`如果找不到副本，子命令将自动打包本地包. 64 | 65 | 一定要看看[您可以指定的元数据](./manifest.zh.md#package-metadata)确保您的箱子更容易被发现! 66 | 67 | ### 为已存在的 crate，发布一个新版本 68 | 69 | 要发布新版本，请在`Cargo.toml`更改`version`为您指定的值。记住[semver 规则](./manifest.zh.md#the-version-field)。然后可选择运行`cargo package`，如果你想检查一下`*.crate`发布前的新版本文件，然后运行`cargo publish`上传新版本. 70 | 71 | ### 管理一个 基于 crates.io 的 crate 72 | 73 | 箱的管理主要通过命令行完成`cargo`工具，而不是[crates.io]网络界面。为此，有一些子命令来管理包. 74 | 75 | #### `cargo yank` 76 | 77 | 在您发布时，实际上可能会因某种原因，而最终破坏的箱子版本(语法错误，忘记包含文件等)的情况。对于诸如此类的情况，Cargo 支持一个箱子版本的"yank"。 78 | 79 | ```console 80 | $ cargo yank --vers 1.0.1 81 | $ cargo yank --vers 1.0.1 --undo 82 | ``` 83 | 84 | 一个 yank **不是**删除任何代码。例如，此功能不用于删除意外上传的机密。如果发生这种情况，您必须立即重置这些秘密. 85 | 86 | 一个 yank 版本的语义是，不为该版本创建新的依赖项，但所有现有的依赖项继续有效。[crates.io]其中一个主要目标是作为永久存档的箱子库，不会随着时间的推移而改变，而允许删除版本将违背这一目标。所以基本上，一个 yank 意味着所有包的`Cargo.lock`不会被破坏，在任何的未来，`Cargo.lock`生成的文件不会列出 yank 的版本。(成为了一个孤岛版本) 87 | 88 | #### `cargo owner` 89 | 90 | 箱子通常由不止一个人开发，或者主要维护者可能会随着时间而改变!箱子的所有者是唯一允许发布新版本箱子的人，但是所有者可以指定其他所有者。 91 | 92 | ```console 93 | $ cargo owner --add my-buddy 94 | $ cargo owner --remove my-buddy 95 | $ cargo owner --add github:rust-lang:owners 96 | $ cargo owner --remove github:rust-lang:owners 97 | ``` 98 | 99 | 给这些命令的所有者 ID 必须是 GitHub 用户名或 GitHub 团队. 100 | 101 | 如果用`--add`了一个用户名，那该用户成为"命名"所有者，拥有该箱子的完全权利。除了能够发布或 yank 箱子的版本，他们还能够添加或删除所有者，*包含*任命*他们*的所有者。毋庸置疑，你不应该让那些你不完全信任的人，作命名所有者。要成为命名所有者，用户必须之前就已登录[crates.io]。 102 | 103 | 如果用`--add`了一个团队，那该团队成为"团队"所有者，对箱的权利受到限制。虽然他们有权发布或 yank 箱子的版本，但他们*不*能够添加或删除所有者。除了更方便管理所有者群体之外，团队还可以更安全地防止恶意所有者。 104 | 105 | 团队的目前的语法是`github:org:team`(见上面的例子)。要将团队添加为所有者，必须是该团队的成员。删除所有者的团队就没有此类限制. 106 | 107 | ### GitHub 权限 108 | 109 | 团队成员资格，不是 GitHub 提供的简单公共访问权限，并且在使用它时可能会遇到以下消息: 110 | 111 | > 您似乎无权从 GitHub 查询必要的属性，来完成此请求。您可能需要在[crates.io]重新进行身份验证，并申请阅读 GitHub 组织成员资格的权限。去看看 112 | 113 | 这基本上是一个全查询防御，当"你试图查询团队信息，而其中的五级成员访问控制，拒绝了它"。这并不夸张。GitHub 对团队访问控制的支持是企业级. 114 | 115 | 最可能的原因是您最后一次登录是在添加此功能之前。我们最初*没有*要求 GitHub 对用户进行身份验证时的权限，因为我们实际上并没有将用户的令牌用于登录以外的任何其他内容。但是，为了代表您能够查询团队成员资格，我们现在需要[`read:org`范围权限][oauth-scopes]。 116 | 117 | 您完全可以拒绝我们这个范围，且在团队介绍之前所做的一切，都将继续有效。但是，您永远无法将团队添加为所有者，或者将团队作为团队所有者发布。如果您尝试这样做，您将收到上述错误。如果你试图发布一个你根本不拥有的箱子，但恰好有一个团队，你可能也会看到这个错误。 118 | 119 | 如果你改变主意，或者只是不确定是否[crates.io]有足够的许可，你可以随时去查看，[crates.io]会提示您，它没有获得它想要的所有范围许可。 120 | 121 | 查询 GitHub 的另一个障碍，是组织可能会主动拒绝第三方访问。要检查这一点，您可以访问: 122 | 123 | ``` 124 | https://github.com/organizations/:org/settings/oauth_application_policy 125 | ``` 126 | 127 | 这里的`:org`是组织的名称(例如 rust-lang)。你可能会看到类似的东西: 128 | 129 | ![Organization Access Control](../images/org-level-acl.png) 130 | 131 | 你可以选择，从您组织的黑名单中，明确删除[crates.io]，或只需按"删除限制(Remove Restrictions)"按钮，允许所有第三方应用程序访问此数据。 132 | 133 | 或者，当[crates.io]请求了`read:org`范围，您可以明确进入白名单的[crates.io]，能查询组织的问题，通过按其名称旁边的"授予访问权限(Grant Access)"按钮: 134 | 135 | ![Authentication Access Control](../images/auth-level-acl.png) 136 | 137 | [crates.io]: https://crates.io/ 138 | [oauth-scopes]: https://developer.github.com/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/ 139 | -------------------------------------------------------------------------------- /docs/css/general.css: -------------------------------------------------------------------------------- 1 | /* Base styles and content styles */ 2 | 3 | @import 'variables.css'; 4 | 5 | :root { 6 | /* Browser default font-size is 16px, this way 1 rem = 10px */ 7 | font-size: 62.5%; 8 | } 9 | 10 | html { 11 | font-family: "Open Sans", sans-serif; 12 | color: var(--fg); 13 | background-color: var(--bg); 14 | text-size-adjust: none; 15 | -webkit-text-size-adjust: none; 16 | } 17 | 18 | body { 19 | margin: 0; 20 | font-size: 1.6rem; 21 | overflow-x: hidden; 22 | } 23 | 24 | code { 25 | font-family: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace !important; 26 | font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */ 27 | } 28 | 29 | /* Don't change font size in headers. */ 30 | h1 code, h2 code, h3 code, h4 code, h5 code, h6 code { 31 | font-size: unset; 32 | } 33 | 34 | .left { float: left; } 35 | .right { float: right; } 36 | .boring { opacity: 0.6; } 37 | .hide-boring .boring { display: none; } 38 | .hidden { display: none !important; } 39 | 40 | h2, h3 { margin-top: 2.5em; } 41 | h4, h5 { margin-top: 2em; } 42 | 43 | .header + .header h3, 44 | .header + .header h4, 45 | .header + .header h5 { 46 | margin-top: 1em; 47 | } 48 | 49 | h1:target::before, 50 | h2:target::before, 51 | h3:target::before, 52 | h4:target::before, 53 | h5:target::before, 54 | h6:target::before { 55 | display: inline-block; 56 | content: "»"; 57 | margin-left: -30px; 58 | width: 30px; 59 | } 60 | 61 | /* This is broken on Safari as of version 14, but is fixed 62 | in Safari Technology Preview 117 which I think will be Safari 14.2. 63 | https://bugs.webkit.org/show_bug.cgi?id=218076 64 | */ 65 | :target { 66 | scroll-margin-top: calc(var(--menu-bar-height) + 0.5em); 67 | } 68 | 69 | .page { 70 | outline: 0; 71 | padding: 0 var(--page-padding); 72 | margin-top: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */ 73 | } 74 | .page-wrapper { 75 | box-sizing: border-box; 76 | } 77 | .js:not(.sidebar-resizing) .page-wrapper { 78 | transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */ 79 | } 80 | 81 | .content { 82 | overflow-y: auto; 83 | padding: 0 15px; 84 | padding-bottom: 50px; 85 | } 86 | .content main { 87 | margin-left: auto; 88 | margin-right: auto; 89 | max-width: var(--content-max-width); 90 | } 91 | .content p { line-height: 1.45em; } 92 | .content ol { line-height: 1.45em; } 93 | .content ul { line-height: 1.45em; } 94 | .content a { text-decoration: none; } 95 | .content a:hover { text-decoration: underline; } 96 | .content img, .content video { max-width: 100%; } 97 | .content .header:link, 98 | .content .header:visited { 99 | color: var(--fg); 100 | } 101 | .content .header:link, 102 | .content .header:visited:hover { 103 | text-decoration: none; 104 | } 105 | 106 | table { 107 | margin: 0 auto; 108 | border-collapse: collapse; 109 | } 110 | table td { 111 | padding: 3px 20px; 112 | border: 1px var(--table-border-color) solid; 113 | } 114 | table thead { 115 | background: var(--table-header-bg); 116 | } 117 | table thead td { 118 | font-weight: 700; 119 | border: none; 120 | } 121 | table thead th { 122 | padding: 3px 20px; 123 | } 124 | table thead tr { 125 | border: 1px var(--table-header-bg) solid; 126 | } 127 | /* Alternate background colors for rows */ 128 | table tbody tr:nth-child(2n) { 129 | background: var(--table-alternate-bg); 130 | } 131 | 132 | 133 | blockquote { 134 | margin: 20px 0; 135 | padding: 0 20px; 136 | color: var(--fg); 137 | background-color: var(--quote-bg); 138 | border-top: .1em solid var(--quote-border); 139 | border-bottom: .1em solid var(--quote-border); 140 | } 141 | 142 | 143 | :not(.footnote-definition) + .footnote-definition, 144 | .footnote-definition + :not(.footnote-definition) { 145 | margin-top: 2em; 146 | } 147 | .footnote-definition { 148 | font-size: 0.9em; 149 | margin: 0.5em 0; 150 | } 151 | .footnote-definition p { 152 | display: inline; 153 | } 154 | 155 | .tooltiptext { 156 | position: absolute; 157 | visibility: hidden; 158 | color: #fff; 159 | background-color: #333; 160 | transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */ 161 | left: -8px; /* Half of the width of the icon */ 162 | top: -35px; 163 | font-size: 0.8em; 164 | text-align: center; 165 | border-radius: 6px; 166 | padding: 5px 8px; 167 | margin: 5px; 168 | z-index: 1000; 169 | } 170 | .tooltipped .tooltiptext { 171 | visibility: visible; 172 | } 173 | 174 | .chapter li.part-title { 175 | color: var(--sidebar-fg); 176 | margin: 5px 0px; 177 | font-weight: bold; 178 | } 179 | 180 | .result-no-output { 181 | font-style: italic; 182 | } 183 | -------------------------------------------------------------------------------- /src/commands/cargo-uninstall.zh.md: -------------------------------------------------------------------------------- 1 | # cargo-uninstall(1) 2 | 3 | ## NAME 4 | 5 | 卸载Cargo-清除 Rust 的二进制文件 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo uninstall` [*options*][_spec_...] 10 | 11 | ## DESCRIPTION 12 | 13 | 此命令将删除随一起安装的软件包[cargo-install(1)](cargo-install.html)这个*规格*参数是要删除的包的包ID规范（请参阅[cargo-pkgid(1)](cargo-pkgid.html)). 14 | 15 | 默认情况下，箱子中的所有二进制文件都会被删除，但`--bin`和`--example`标志只能用于删除特定的二进制文件。 16 | 17 | 按照优先顺序确定安装根目录： 18 | 19 | - `--root`选项 20 | - `CARGO_INSTALL_ROOT`环境变量 21 | - `install.root`Cargo[config value](../reference/config.html) 22 | - `CARGO_HOME`环境变量 23 | - `$HOME/.cargo` 24 | 25 | ## OPTIONS 26 | 27 | ### Install Options 28 | 29 |
30 | 31 |
-p
32 |
--package spec...
33 |
Package to uninstall.
34 | 35 |
--bin name...
36 |
Only uninstall the binary name.
37 | 38 |
--root dir
39 |
Directory to uninstall packages from.
40 | 41 |
42 | 43 | ### Display Options 44 | 45 |
46 | 47 |
-v
48 |
--verbose
49 |
Use verbose output. May be specified twice for "very verbose" output which 50 | includes extra output such as dependency warnings and build script output. 51 | May also be specified with the term.verbose 52 | config value.
53 | 54 |
-q
55 |
--quiet
56 |
Do not print cargo log messages. 57 | May also be specified with the term.quiet 58 | config value.
59 | 60 |
--color when
61 |
Control when colored output is used. Valid values:

62 |
    63 |
  • auto (default): Automatically detect if color support is available on the 64 | terminal.
    • 65 |
  • always: Always display colors.
    • 66 |
  • never: Never display colors.
    • 67 |
68 |

May also be specified with the term.color 69 | config value.

70 | 71 |
72 | 73 | ### Common Options 74 | 75 |
76 | 77 |
+toolchain
78 |
If Cargo has been installed with rustup, and the first argument to cargo 79 | begins with +, it will be interpreted as a rustup toolchain name (such 80 | as +stable or +nightly). 81 | See the rustup documentation 82 | for more information about how toolchain overrides work.
83 | 84 |
-h
85 |
--help
86 |
Prints help information.
87 | 88 |
-Z flag
89 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
90 | 91 |
92 | 93 | ## ENVIRONMENT 94 | 95 | 查看[the reference](../reference/environment-variables.html)有关Cargo读取的环境变量的详细信息。 96 | 97 | ## EXIT STATUS 98 | 99 | - `0`：Cargo成功。 100 | - `101`：Cargo未能完成。 101 | 102 | ## EXAMPLES 103 | 104 | 1. 卸载以前安装的软件包。 105 | 106 | Cargo倾覆 107 | 108 | ## SEE ALSO 109 | 110 | [cargo(1)](cargo.zh.md), [cargo-install(1)](cargo-install.html) 111 | -------------------------------------------------------------------------------- /src/commands/cargo-search.md: -------------------------------------------------------------------------------- 1 | # cargo-search(1) 2 | 3 | ## NAME 4 | 5 | cargo-search - Search packages in crates.io 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo search` [_options_] [_query_...] 10 | 11 | ## DESCRIPTION 12 | 13 | This performs a textual search for crates on . The matching 14 | crates will be displayed along with their description in TOML format suitable 15 | for copying into a `Cargo.toml` manifest. 16 | 17 | ## OPTIONS 18 | 19 | ### Search Options 20 | 21 |
22 | 23 |
--limit limit
24 |
Limit the number of results (default: 10, max: 100).
25 | 26 | 27 |
--index index
28 |
The URL of the registry index to use.
29 | 30 | 31 | 32 |
--registry registry
33 |
Name of the registry to use. Registry names are defined in Cargo config 34 | files. If not specified, the default registry is used, 35 | which is defined by the registry.default config key which defaults to 36 | crates-io.
37 | 38 | 39 | 40 |
41 | 42 | ### Display Options 43 | 44 |
45 |
-v
46 |
--verbose
47 |
Use verbose output. May be specified twice for "very verbose" output which 48 | includes extra output such as dependency warnings and build script output. 49 | May also be specified with the term.verbose 50 | config value.
51 | 52 | 53 |
-q
54 |
--quiet
55 |
Do not print cargo log messages. 56 | May also be specified with the term.quiet 57 | config value.
58 | 59 | 60 |
--color when
61 |
Control when colored output is used. Valid values:

62 |
    63 |
  • auto (default): Automatically detect if color support is available on the 64 | terminal.
    • 65 |
  • always: Always display colors.
    • 66 |
  • never: Never display colors.
    • 67 |
68 |

May also be specified with the term.color 69 | config value.

70 | 71 | 72 |
73 | 74 | ### Common Options 75 | 76 |
77 | 78 |
+toolchain
79 |
If Cargo has been installed with rustup, and the first argument to cargo 80 | begins with +, it will be interpreted as a rustup toolchain name (such 81 | as +stable or +nightly). 82 | See the rustup documentation 83 | for more information about how toolchain overrides work.
84 | 85 | 86 |
-h
87 |
--help
88 |
Prints help information.
89 | 90 | 91 |
-Z flag
92 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
93 | 94 | 95 |
96 | 97 | 98 | ## ENVIRONMENT 99 | 100 | See [the reference](../reference/environment-variables.html) for 101 | details on environment variables that Cargo reads. 102 | 103 | 104 | ## EXIT STATUS 105 | 106 | * `0`: Cargo succeeded. 107 | * `101`: Cargo failed to complete. 108 | 109 | 110 | ## EXAMPLES 111 | 112 | 1. Search for a package from crates.io: 113 | 114 | cargo search serde 115 | 116 | ## SEE ALSO 117 | [cargo(1)](cargo.zh.md), [cargo-install(1)](cargo-install.html), [cargo-publish(1)](cargo-publish.html) 118 | -------------------------------------------------------------------------------- /src/commands/cargo-locate-project.zh.md: -------------------------------------------------------------------------------- 1 | # cargo-locate-project(1) 2 | 3 | ## NAME 4 | 5 | cargo locate项目——打印Cargo的JSON表示。toml文件的位置 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo locate-project` [_options_] 10 | 11 | ## DESCRIPTION 12 | 13 | 这个命令将把一个JSON对象打印到stdout，并带有到`Cargo.toml`显示 14 | 15 | ## OPTIONS 16 | 17 |
18 | 19 |
--workspace
20 |
Locate the Cargo.toml at the root of the workspace, as opposed to the current 21 | workspace member.
22 | 23 |
24 | 25 | ### Display Options 26 | 27 |
28 | 29 |
--message-format fmt
30 |
The representation in which to print the project location. Valid values:

31 |
    32 |
  • json (default): JSON object with the path under the key "root".
    • 33 |
  • plain: Just the path.
    • 34 |
35 | 36 |
-v
37 |
--verbose
38 |
Use verbose output. May be specified twice for "very verbose" output which 39 | includes extra output such as dependency warnings and build script output. 40 | May also be specified with the term.verbose 41 | config value.
42 | 43 |
-q
44 |
--quiet
45 |
Do not print cargo log messages. 46 | May also be specified with the term.quiet 47 | config value.
48 | 49 |
--color when
50 |
Control when colored output is used. Valid values:

51 |
    52 |
  • auto (default): Automatically detect if color support is available on the 53 | terminal.
    • 54 |
  • always: Always display colors.
    • 55 |
  • never: Never display colors.
    • 56 |
57 |

May also be specified with the term.color 58 | config value.

59 | 60 |
61 | 62 | ### Manifest Options 63 | 64 |
65 |
--manifest-path path
66 |
Path to the Cargo.toml file. By default, Cargo searches for the 67 | Cargo.toml file in the current directory or any parent directory.
68 | 69 |
70 | 71 | ### Common Options 72 | 73 |
74 | 75 |
+toolchain
76 |
If Cargo has been installed with rustup, and the first argument to cargo 77 | begins with +, it will be interpreted as a rustup toolchain name (such 78 | as +stable or +nightly). 79 | See the rustup documentation 80 | for more information about how toolchain overrides work.
81 | 82 |
-h
83 |
--help
84 |
Prints help information.
85 | 86 |
-Z flag
87 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
88 | 89 |
90 | 91 | ## ENVIRONMENT 92 | 93 | 查看[the reference](../reference/environment-variables.html)有关Cargo读取的环境变量的详细信息。 94 | 95 | ## EXIT STATUS 96 | 97 | - `0`：Cargo成功。 98 | - `101`：Cargo未能完成。 99 | 100 | ## EXAMPLES 101 | 102 | 1. 根据当前目录显示清单的路径： 103 | 104 | Cargo定位项目 105 | 106 | ## SEE ALSO 107 | 108 | [cargo(1)](cargo.zh.md), [cargo-metadata(1)](cargo-metadata.html) 109 | -------------------------------------------------------------------------------- /src/appendix/glossary.zh.md: -------------------------------------------------------------------------------- 1 | # Glossary 2 | 3 | - 词汇表 4 | 5 | ### Artifact 6 | 7 | - 工件 8 | 9 | 一个*Artifact*是由编译过程创建的文件或文件集。这包括可链接库和可执行二进制文件. 10 | 11 | ### Crate 12 | 13 | - 箱 (包/库， 又一抽象名) 14 | 15 | 包中的每个目标都是*箱*。Crates 是库或可执行二进制文件。它可能松散地引用目标的源代码或目标生成的编译工件。一个箱也可以指从注册表中提取的压缩包. 16 | 17 | ### Edition 18 | 19 | - 版本 20 | 21 | 一个*Rust Edition*是 Rust 语言的开发里程碑。该[一个包的版本][edition-field]在`Cargo.toml`清单中指定，各个目标可以指定它们使用的版本。见[版本指南][edition guide]欲获得更多信息. 22 | 23 | ### Feature 24 | 25 | - 特性/特征/功能 26 | 27 | 一个[_特征_][feature]是一个允许条件编译的命名标志参数。一个特性可以引用可选的依赖项，或者在 一个`Cargo.toml` 中定义的任意名称，可以键入(使用到)源代码中。 28 | 29 | Cargo 有[_不稳定的特征标志_][cargo-unstable]，这可以用来实现 Cargo 本身的实验行为。Rust 编译器和 Rustdoc 也有自己的不稳定特征标志(参见[不稳定的书][unstable-book]和[Rustdoc 书][rustdoc-unstable]). 30 | 31 | ### Index 32 | 33 | - 索引是注册表中，可搜索的包的列表. 34 | 35 | ### Lock file 36 | 37 | - (锁定/锁) 文件 38 | 39 | `Cargo.lock`，名:_锁定文件_，是一个文件，用于捕获工作空间或包中使用的每个依赖项的确切版本，它由 Cargo 自动生成。看到[Cargo.toml 与 Cargo.lock][cargo.toml vs cargo.lock]. 40 | 41 | ### Manifest 42 | 43 | - 清单/元信息 44 | 45 | 一个[_清单_][manifest]是对包或工作空间的描述，名为`Cargo.toml`. 46 | 47 | 一个[_虚拟清单_][virtual]是一个`Cargo.toml`，仅描述工作空间的文件，不包含包。 48 | 49 | ### Member 50 | 51 | - 会员/成员 52 | 53 | 一个*成员*是属于工作空间的一个包. 54 | 55 | ### Package 56 | 57 | - 包 58 | 59 | 一个*包*是源文件和描述包的清单`Cargo.toml`的集合。包具有名称和版本，用于指定包之间的依赖关系。包中包含多个目标，这些目标是库或可执行二进制文件。 60 | 61 | 该*包根*是`Cargo.toml`清单位于的包的目录。 62 | 63 | 该[_包 ID 规范_][pkgid-spec]， 要么*SPEC*，是一个字符串，用于辨识从特定源，引用特定版本的包唯一性。 64 | 65 | ### Project 66 | 67 | - 包/项目 68 | 69 | [package](#package)的另一个名字. 70 | 71 | ### Registry 72 | 73 | - 注册表 74 | 75 | 一个*注册处*是一种服务，包含可下载的包，可以安装或用作包的依赖项.默认注册表是[crates.io](https://crates.io)。注册表有一个*索引*，其中包含所有包装箱的清单，并告诉 Cargo 如何下载所需的箱。 76 | 77 | ### Source 78 | 79 | - 源/资源 80 | 81 | 一个*源*是一个提供程序，包含箱子，这些箱子可当依赖项的包。有几种源: 82 | 83 | - **注册表来源**- 见[注册表](#registry). 84 | - **本地注册表源**- 在文件系统上存储为压缩文件的一组包。看到[本地注册表来源][local registry sources]. 85 | - **目录来源**- 在文件系统上存储为未压缩文件的一组包.看到[目录来源][directory sources]. 86 | - **路径来源**- 位于文件系统上的单个包(例如[路径依赖][path dependency])或一组多个包(如[路径覆盖][path overrides]). 87 | - **Git 来源**- 位于 git 存储库中的包(例如[git 依赖][git dependency]要么[git 来源][git source]). 88 | 89 | 看到[来源更换][source replacement]欲获得更多信息. 90 | 91 | ### Spec 92 | 93 | - 看到[包 ID 规范](#package). 94 | 95 | ### Target 96 | 97 | - 目标 98 | 99 | *Target*这个词的意思，取决于具体情况: 100 | 101 | - **Cargo 目标** - Cargo 项目会有*target*，其具有对应将要生成的工件。项目可以包含库，二进制，示例，测试和基准目标。该[目标列表][targets]配置在`Cargo.toml`清单，通常由源文件的[目录布局][directory layout]自动推断的。 102 | - **目标架构**- 构建工件的 OS 和机器体系结构，通常称为一个*目标*。 103 | - **目标 三元(Triple)**- 三元组是用于指定目标体系结构的特定格式。见[clang 文档][clang documentation] 了解详情。三元组可以称为 一个*目标三元*，此为产生的工件的架构，以及*主机三元*，此为编译器运行的体系结构。可以使用`--target`命令行选项或`build.target` [配置选项]指定目标三元组。 104 | - **目标目录**- Cargo 将所有构建的工件和中间文件放入*target*目录。默认情况下，这是一个名为`target`的目录会在工作区根目录，或者包根(如果不使用工作空间)。目录随着`--target-dir`命令行选项，`CARGO_TARGET_DIR` [环境变量][environment variable]， 或者`build.target-dir` 105 | [配置选项][config option]改变而改变. 106 | 107 | 108 | > “target-triple (目标 三元)" 是 编译器的 专用术语，用 “ cpu- vendor- os" 来标识 交叉编译时的 系统类型 109 | 110 | ### Test Targets 111 | 112 | Cargo*测试目标*生成二进制文件，帮助验证代码的正确操作和正确性。有两种类型的测试工件: 113 | 114 | - **单元测试**- 一个*单元测试*是直接从库或二进制目标编译的可执行二进制文件。它包含库或二进制代码的全部内容，并运行`#[test]`注释函数，用于验证各个代码单元。 115 | - **集成测试目标**- 一个[_集成测试目标_][integration-tests]是一个来自*测试目标*的可执行的二进制文件，这是一个独特的箱子，其来源位于`tests`目录或由在`Cargo.toml`清单里面的[`[[test]]`表][targets]指定。它旨在仅测试库的公共 API，或执行二进制文件以验证其操作。 116 | 117 | ### Workspace 118 | 119 | - 工作区 120 | 121 | 一个[_工作区_][workspace]是一个共享公共依赖项解析(具有共享`Cargo.lock`)，输出目录和各种设置，如配置文件，的一个或多个包的集合。 122 | 123 | 一个[_虚拟工作区_][virtual]是`Cargo.toml`清单根目录的工作空间， 没有定义包，只列出工作区成员。 124 | 125 | 该*工作区根*是工作区的`Cargo.toml`清单位于的目录. 126 | 127 | [cargo.toml vs cargo.lock]: ../cargo-toml-vs-cargo-lock.zh.md 128 | [directory sources]: ../reference/source-replacement.zh.md#directory-sources 129 | [local registry sources]: ../reference/source-replacement.zh.md#local-registry-sources 130 | [source replacement]: ../reference/source-replacement.zh.md 131 | [cargo-unstable]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.zh.md 132 | [clang documentation]: http://clang.llvm.org/docs/CrossCompilation.zh.md#target-triple 133 | [config option]: ../reference/config.zh.md 134 | [directory layout]: ../reference/manifest.zh.md#the-project-layout 135 | [edition guide]: https://rust-lang-nursery.github.io/edition-guide/ 136 | [edition-field]: ../reference/manifest.zh.md#the-edition-field-optional 137 | [environment variable]: ../reference/environment-variables.zh.md 138 | [feature]: ../reference/manifest.zh.md#the-features-section 139 | [git dependency]: ../reference/specifying-dependencies.zh.md#specifying-dependencies-from-git-repositories 140 | [git source]: ../reference/source-replacement.zh.md 141 | [integration-tests]: ../reference/manifest.zh.md#integration-tests 142 | [manifest]: ../reference/manifest.zh.md 143 | [path dependency]: ../reference/specifying-dependencies.zh.md#specifying-path-dependencies 144 | [path overrides]: ../reference/specifying-dependencies.zh.md#overriding-with-local-dependencies 145 | [pkgid-spec]: ../reference/pkgid-spec.zh.md 146 | [rustdoc-unstable]: https://doc.rust-lang.org/nightly/rustdoc/unstable-features.zh.md 147 | [targets]: ../reference/manifest.zh.md#configuring-a-target 148 | [unstable-book]: https://doc.rust-lang.org/nightly/unstable-book/index.zh.md 149 | [virtual]: ../reference/manifest.zh.md#virtual-manifest 150 | [workspace]: ../reference/manifest.zh.md#the-workspace-section 151 | -------------------------------------------------------------------------------- /src/commands/cargo-locate-project.md: -------------------------------------------------------------------------------- 1 | # cargo-locate-project(1) 2 | 3 | ## NAME 4 | 5 | cargo-locate-project - Print a JSON representation of a Cargo.toml file's location 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo locate-project` [_options_] 10 | 11 | ## DESCRIPTION 12 | 13 | This command will print a JSON object to stdout with the full path to the 14 | `Cargo.toml` manifest. 15 | 16 | ## OPTIONS 17 | 18 |
19 | 20 |
--workspace
21 |
Locate the Cargo.toml at the root of the workspace, as opposed to the current 22 | workspace member.
23 | 24 | 25 |
26 | 27 | ### Display Options 28 | 29 |
30 | 31 |
--message-format fmt
32 |
The representation in which to print the project location. Valid values:

33 |
    34 |
  • json (default): JSON object with the path under the key "root".
    • 35 |
  • plain: Just the path.
    • 36 |
37 | 38 | 39 |
-v
40 |
--verbose
41 |
Use verbose output. May be specified twice for "very verbose" output which 42 | includes extra output such as dependency warnings and build script output. 43 | May also be specified with the term.verbose 44 | config value.
45 | 46 | 47 |
-q
48 |
--quiet
49 |
Do not print cargo log messages. 50 | May also be specified with the term.quiet 51 | config value.
52 | 53 | 54 |
--color when
55 |
Control when colored output is used. Valid values:

56 |
    57 |
  • auto (default): Automatically detect if color support is available on the 58 | terminal.
    • 59 |
  • always: Always display colors.
    • 60 |
  • never: Never display colors.
    • 61 |
62 |

May also be specified with the term.color 63 | config value.

64 | 65 | 66 |
67 | 68 | ### Manifest Options 69 | 70 |
71 |
--manifest-path path
72 |
Path to the Cargo.toml file. By default, Cargo searches for the 73 | Cargo.toml file in the current directory or any parent directory.
74 | 75 | 76 |
77 | 78 | ### Common Options 79 | 80 |
81 | 82 |
+toolchain
83 |
If Cargo has been installed with rustup, and the first argument to cargo 84 | begins with +, it will be interpreted as a rustup toolchain name (such 85 | as +stable or +nightly). 86 | See the rustup documentation 87 | for more information about how toolchain overrides work.
88 | 89 | 90 |
-h
91 |
--help
92 |
Prints help information.
93 | 94 | 95 |
-Z flag
96 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
97 | 98 | 99 |
100 | 101 | 102 | ## ENVIRONMENT 103 | 104 | See [the reference](../reference/environment-variables.html) for 105 | details on environment variables that Cargo reads. 106 | 107 | 108 | ## EXIT STATUS 109 | 110 | * `0`: Cargo succeeded. 111 | * `101`: Cargo failed to complete. 112 | 113 | 114 | ## EXAMPLES 115 | 116 | 1. Display the path to the manifest based on the current directory: 117 | 118 | cargo locate-project 119 | 120 | ## SEE ALSO 121 | [cargo(1)](cargo.zh.md), [cargo-metadata(1)](cargo-metadata.html) 122 | -------------------------------------------------------------------------------- /src/commands/cargo-uninstall.md: -------------------------------------------------------------------------------- 1 | # cargo-uninstall(1) 2 | 3 | ## NAME 4 | 5 | cargo-uninstall - Remove a Rust binary 6 | 7 | ## SYNOPSIS 8 | 9 | `cargo uninstall` [_options_] [_spec_...] 10 | 11 | ## DESCRIPTION 12 | 13 | This command removes a package installed with [cargo-install(1)](cargo-install.html). The _spec_ 14 | argument is a package ID specification of the package to remove (see 15 | [cargo-pkgid(1)](cargo-pkgid.html)). 16 | 17 | By default all binaries are removed for a crate but the `--bin` and 18 | `--example` flags can be used to only remove particular binaries. 19 | 20 | The installation root is determined, in order of precedence: 21 | 22 | - `--root` option 23 | - `CARGO_INSTALL_ROOT` environment variable 24 | - `install.root` Cargo [config value](../reference/config.html) 25 | - `CARGO_HOME` environment variable 26 | - `$HOME/.cargo` 27 | 28 | 29 | ## OPTIONS 30 | 31 | ### Install Options 32 | 33 |
34 | 35 |
-p
36 |
--package spec...
37 |
Package to uninstall.
38 | 39 | 40 |
--bin name...
41 |
Only uninstall the binary name.
42 | 43 | 44 |
--root dir
45 |
Directory to uninstall packages from.
46 | 47 | 48 |
49 | 50 | ### Display Options 51 | 52 |
53 | 54 |
-v
55 |
--verbose
56 |
Use verbose output. May be specified twice for "very verbose" output which 57 | includes extra output such as dependency warnings and build script output. 58 | May also be specified with the term.verbose 59 | config value.
60 | 61 | 62 |
-q
63 |
--quiet
64 |
Do not print cargo log messages. 65 | May also be specified with the term.quiet 66 | config value.
67 | 68 | 69 |
--color when
70 |
Control when colored output is used. Valid values:

71 |
    72 |
  • auto (default): Automatically detect if color support is available on the 73 | terminal.
    • 74 |
  • always: Always display colors.
    • 75 |
  • never: Never display colors.
    • 76 |
77 |

May also be specified with the term.color 78 | config value.

79 | 80 | 81 | 82 |
83 | 84 | ### Common Options 85 | 86 |
87 | 88 |
+toolchain
89 |
If Cargo has been installed with rustup, and the first argument to cargo 90 | begins with +, it will be interpreted as a rustup toolchain name (such 91 | as +stable or +nightly). 92 | See the rustup documentation 93 | for more information about how toolchain overrides work.
94 | 95 | 96 |
-h
97 |
--help
98 |
Prints help information.
99 | 100 | 101 |
-Z flag
102 |
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for details.
103 | 104 | 105 |
106 | 107 | 108 | ## ENVIRONMENT 109 | 110 | See [the reference](../reference/environment-variables.html) for 111 | details on environment variables that Cargo reads. 112 | 113 | 114 | ## EXIT STATUS 115 | 116 | * `0`: Cargo succeeded. 117 | * `101`: Cargo failed to complete. 118 | 119 | 120 | ## EXAMPLES 121 | 122 | 1. Uninstall a previously installed package. 123 | 124 | cargo uninstall ripgrep 125 | 126 | ## SEE ALSO 127 | [cargo(1)](cargo.zh.md), [cargo-install(1)](cargo-install.html) 128 | --------------------------------------------------------------------------------